Mid Term Report and Code Review - HLA interfaces for ns-3

Hello Everyone,

The updated wiki of the project can be checked here:
https://www.nsnam.org/wiki/index.php/GSOC2012HLA
The code review request can patches can be viewed here:
http://codereview.appspot.com/6349088/
The Mid Term Report is also available here:
https://www.nsnam.org/wiki/index.php/GSOC2012HLAMidTerm

Achieved Goals
============

During the first week of GSoC we worked on a RTI sheduler. This scheduler
was suppose to receive messages from RTI through ns-3 federate and had map
data structure. It was suppose to convert these messages received into ns-3
events. After few days we analysed the design and figured out that there
could be a easier way of doing this by just modifying an implementation of
src/syncronization.cc that is wall-clock-syncronizer.cc and using a
real-time-simulater-impl.cc as a simulator. Thus, we changed our design a
bit. By the end of second week the new design was ready and we were in
touch with the portico community and discussed the project. After input
from them we finalised the design. We chucked the RTI scheduler module,
although some part of the code was reusable.

Next, we worked on getting portico up and running some example federates
and creating a federation using two or more federates. Then using the
poRTIco documentation we wrote some ns3Federate. ns3Federate basically has
the definition for setting up a federation and enabling various features
for ns-3 like time definitions. It also creates objects, sets basic
attributes and publish and subscribe these objects. Objects can also be
registered and deleted through this. It also contains the main simulation
loop with all the above mentioned events in order. After ns3Federate we
worked with ns3FedAmb (Federate Ambassador), this basically handles
callbacks which the RTI (poRTIco in our case) sends them to ns-3 as and
when an object is published, subscribed, deleted or any attribute is
changed. A callback is also received in case of a time advance request
grant. So, all in all the two classes provide an interface to communicate
with the RTI and help in basic synchronisation of the events with other
federates by receiving time advance granted callbacks.

Once we were through with this, we had a lot of code but nothing to test
it. So, we worked on developing another set of federate and federate
ambassador, called dummy and dummyFederateAmbassador. The features of these
two were similar to ns-3 but this federate also had a small simulation. It
changed the attributes of the object published by ns-3, it changed the
MsgType i.e. the type of message to be sent and the Msg i.e. actual text
(planning to change it to data rate and delay), so when this federate was
run in parallel with ns-3 federate, various functions could be easily
tested, like if ns-3 is receiving callbacks when the attributes are
changed? and is the changed values of the attributes reflected? After
getting rid of some initial bugs everything worked fine.

Next aim was to get these callbacks and messages into ns-3 main code (C++).
So a C++ class was created, server.cc. Further, in ns3FedAmb sockets were
added. A master - slave configuration was set up between ns3FedAmb and
server.cc. When simulation was to be started, finished, object attributes
are updated, new objects are published or time advance is granted
ns3FedAmb sends a specific string to a given port along with the
accompanied message. Server.cc was a simple test program, it reads throgh a
port (same as ns3FedAmb) and accordingly take decision. Like on time
advance a variable RTI_CLK is incremented. Rest functions for now were only
for proof of concept. We also implemented a different thread which hears
from ns3FedAmb and main thread can work on something else. It is a
requirement since when ns-3 will be handling events from other simulator,
it will also have it's own work/events.

Next, we integrated this server.cc code to one of the ns-3 examples for fun
(It could later help in developing the HLA API) now a ns-3 example first.cc
receives messages from RTI, thus other federates. We tested this by running
ns3Fedrate in one shell and parallel running dummy in another shell and
first.cc in another. Object was published by ns-3 and dummy both and
modified by dummy at each iteration. These changes were transferred to
ns3Fedrate and subsequently first.cc and that too keeping time in mind,
i.e. synchronised. A  very crude form of HLA established. After this we
started refining the server.cc and changed it to link-to-rti.cc and
link-to-rti.h. The work on this is still under progress, the idea is that
this could be included by hla and user can have API access to these
function.

Future Goals
=========

Once link-to-rti is complete we plan to work on Synchronisation and API
simultaneously. Then we plan to write some examples to demonstrate the use
of API and possible an API test.

Synchronisation as of now looks pretty straight forward, although we do
have to check it. It seems that just by using the
real-time-simulator-impl.cc as the default simulator for hla and changing a
synchronizer.cc implementation, i.e. wall-clock-synchronizer.cc to send RTI
time as real time, events could be scheduled to RTI time. Moreover, a
single function GerRealTime() at presents gives real time, changing it to
fetch the value of RTI_CLK might do the trick.

API will be designed for accessing various functions of link-to-rti and
also giving the user option to create publishable objects, set and read
characteristics.

Known Issues/Limitations
==================

One of the known issue is that the time advance request grated by RTI are
not consistent at times, we are in touch with portico community to figure
out what is the problem with our implementation.

A limitation of the present model is that ns-3 acts as a sink and not a
source, which we added as a future milestone. Moreover the federate at
present is not sending interaction only publishing objects, another future
milestone.

Please contact if any part needs further detailing and if there is an issue
with the code. Thank you for your time.

Best Regards,

Mudit Raj Gupta