Nsnam - User contributions [en]

GSOC2019PatchRequirement

2019-03-26T15:00:16Z

Krotov: Add link to GitLab issues

As part of their Google Summer of Code 2019 applications to ns-3, we require that students produce at least a small amount of code for ns-3. This will allow us to gauge your ability to dive into source code, understand it, make a modification, and proceed to build and verify if your modification works.

Students can submit patches to our existing open issues, or point us to code that you have already submitted for review, or if you are new to ns-3, we provide below a small coding project that you can work on and submit with your application.

* If you already have contributed a patch for ns-3 in the past, please check with the org admins whether the patch requirement can be satisfied by this prior code. If you have code posted somewhere else (GitHub, for example, or a class project page) that you feel is a good indicator of your ability to write ns-3 code, please point us to the URL.
* If not the above, either complete the minimum requirement test given below, or pick a bug in our [https://gitlab.com/nsnam/ns-3-dev/issues GitLab issue list] or [https://www.nsnam.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=64089&order=bug_id%20DESC&query_format=specific Bugzilla] that does not already have a patch pending, and try to fix it.

In summary, students must (1) satisfy either the minimum required patch below or else provide a pointer to a comparable piece of ns-3 code that they have authored, and optionally (2) also contribute code to fix something in ns-3, even if only a small improvement to the codebase or documentation.

== Minimum requirement patch ==

=== Setting up the environment ===

Perform the following steps (you may want to review our [[Installation]] page):

* Download the ns-3-dev repository, or clone it from Git:

$: git clone https://gitlab.com/nsnam/ns-3-dev.git
$: cd ns-3-dev
$: git checkout -b patch-requirement origin/master

* Verify if you can build ns-3 and run the test suite:

$: ./waf configure --disable-python --enable-examples
$: ./waf build
$: ./test.py

=== Objective ===

In ns-3, a preferred way to split module dependencies is to use a callback. For instance, a hypothetical L3 protocol can directly call methods on a NetDevice (e.g., Send()) to perform operations. But when a NetDevice has to call the above layer, the callback mechanism comes into play: since it is not possible for a NetDevice to know what future network layer will be placed on top of it, it must rely, in general, on callbacks. This kind of connection is prevalent inside a Node: if you take a look at node.cc, you will see that forwarding packets from NetDevice to a L3 layer is done through callbacks. Any L3 protocol has to register its own handler that will be called if the protocol number matches the number on the packet.

The objective of this patch is to add a new, simple, basic, L3 protocol, with the protocol number 99. The new protocol implementation should be registered on the node, and it should be able to send a ping packet, and receive a response. That is, it does not need to do routing or introduce any new addressing scheme; it merely needs to be able to send a 'ping-like' packet to the NetDevice, and receive a packet (destined to protocol 99) from a NetDevice. A simple print on the screen at the send and receive moment is enough to show a working implementation.

=== What to submit ===

* A patch to ns-3-dev that accomplishes the objectives. In your GSoC application, point us to a publicly available URL where you've hosted the patch (such as a "gist" on github.com for instance). See also some guidelines [http://www.nsnam.org/developers/contributing-code/submit/ here] about formatting patches for review. If you need help with this step, contact the ns-3 Org Admin (Tom Henderson) for advice.

'''Note:''' Keep your solution private by pasting the link in your application to Google, not posting it on the mailing list.

GSOC2019Projects

2019-02-05T16:43:08Z

Krotov: /* Structured logging support */

{{TOC}}

This page contains 2019 Google Summer of Code project ideas for ns-3.

'''Important note:''' Google has not selected participating open source projects yet; we are only in the application phase.

* [http://www.google-melange.com/gsoc/document/show/gsoc_program/google/gsoc2015/help_page GSoC Frequently Asked Questions]
* [[GSOC2018StudentGuide |ns-3's 2018 GSoC Student guide]]
* [http://en.flossmanuals.net/GSoCStudentGuide/ GSoC student guide (not ns-3 specific)]
* [[GSOC2018StudentApplicationTemplate |2018 GSoC Student application template]]
* [[GSOCMentorGuide | ns-3's GSoC Mentor guide]]
* [http://en.flossmanuals.net/gsoc-mentoring/ GSoC Mentor guide (not ns-3 specific)]
* [[GSOCSelectionProcess | GSoC Student Selection Process]]
* ''Get in contact with the ns-3 team'': [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers mailing list] | ''chat'' https://ns-3.zulipchat.com/

=== About the ns-3 project ===

ns-3 is a discrete-event network simulator, with a particular emphasis on network research and education.

Users of ns-3 can construct simulations of computer networks using models of traffic generators, protocols such as TCP/IP, and devices and channels such as WiFi, and analyze or visualize the results. Simulation plays a vital role in the research and education process, because of the ability for simulations to obtain reproducible results (particularly for wireless protocol design), scale to large networks, and study systems that have not yet been implemented. A particular emphasis in ns-3 is the high degree of realism in the models (including frameworks for real application and kernel code) and integration of the tool with virtual machine environments and testbeds; we view that researchers need to move more effortlessly between simulation, testbeds, and live experiments, and ns-3 is designed to facilitate that.

Google Summer of Code organizational admins for ns-3 are [mailto:tpecorella@mac.com Tommaso Pecorella] and [mailto:tomh@tomh.org Tom Henderson]; contact them with any questions. They also hang out on [https://ns-3.zulipchat.com Zulip]. The project has participated in past GSoCs during 2008-10, 2012-15, and 2017-18.

Mentors will be paired with students based on the projects that are selected. Mentors from companies are welcome, if the employer will permit the mentor sufficient time to perform the mentoring. Prospective mentors should notify Tom Henderson or Tommaso Pecorella of interest. Mentors familiar with ns-3 development practices will be preferred, to improve the chances of student code merge. In 2019, we are going to be seeking two-person mentoring teams for projects, to help with the mentoring workload and bring more expertise.

=== Students: how to participate ===

For students interested in applying to ns-3 for GSOC, first wait to see if ns-3 will be selected. If so, then go through the following list to get started:
* Read the official [http://en.flossmanuals.net/GSoCStudentGuide/ GSoC student guide].
* Read [[GSOC2018StudentGuide |ns-3's GSoC Student guide]].
* Look through our [[#Project Ideas]] below to see if you find a project that interests you.
* Review the [http://www.nsnam.org/ns-3-29/documentation/ns-3 tutorial] thoroughly, if you have not already done so.
* Look through the [[GSOC2018StudentApplicationTemplate |GSoC Student application template]] to start preparing your proposal.
* Next, proceed to get in touch with the developers on the mailing list and refine your proposal.
* In parallel, make sure you prepare a patch as per the [[GSOC2018PatchRequirement | Patch Requirement Guidelines]] (to be revised). Your application to ns-3 will not be considered if you do not fulfill this requirement.

Below is a list of [[#Project Ideas]] proposed by the ns-3 team for Google Summer of Code 2019. Please note that these ideas are not limited to GSoC; anyone is welcome to work on them. Please email the [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers list] if you have a different idea that you'd like to work on, to see if a mentor may be interested. Applicants are encouraged to look over this list, pick one that especially interests them, think about it, and discuss potential approaches on the [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers list]. Previous experience with the Google Summer of Code programmes suggest that the more you discuss and refine your proposal on the mailing list beforehand, the stronger the proposal it will develop into, and the higher your chances of being accepted into the programme.

<blockquote>
Each project idea within a particular priority has been tagged with the following properties:
* ''Required Experience:'' Languages, concepts, or packages with which applicants must be familiar.
* ''Bonus Experience:'' Other experience or familiarity which would be greatly helpful to applicants for this project.
* ''Interests:'' Areas of particular relevance to this project, and an indicator of where successful students might apply their experiences coming out of this project.
* ''Difficulty:'' easy, medium or difficult
* ''Recommended reading:'' pointers to documentation, papers, specific bugs, etc.

Note that all of the projects require some experience and comfort with C++. Project ideas for which C++ is noted as a required experience will require more and deeper familiarity with the language. A similar notion applies to computer networking, BSD sockets, etc: Familiarity is strongly preferred, but is not required except where explicitly noted due to the topic being more advanced in that regard.
</blockquote>

=== Mentors: how to participate ===

The ns-3 project is open to the proposal of new project ideas by developers interested in being a GSoC mentor. For mentors who're adding project ideas to the list below, please ensure that:

* The projects are sized such that there can be a code merge by the end of the coding period. The scope of the project should be such that it is very difficult to not have a code merge by the end of the summer.
* The proposed projects are not too open-ended. That is, if the deliverables or a clear path to the same are not well understood, it is better kept outside GSOC.
* There should be a clear merge path to one of the main project code repositories (ns-3-dev, ns-3-dce, bake) by the end of the summer, either because the patches directly apply to these repositories, or because they apply to an ns-3 module that is in the process of being merged with ns-3-dev.

== Project Ideas ==

'''Note to students:''' These ideas are not listed in any priority order. The list of mentors for 2019 includes Mohit Tahiliani, Alexander Krotov, Abhijith Anilkumar, Ankit Deepak, Dizhi Zhou, and Gabriel Arrobo, and others are in discussion.

==== Usability improvements ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], Dizhi Zhou, others TBD

Usability of ns-3 can always be improved, whether it is help with building simulations, running simulation campaigns, using the ns-3 C++ API, improving the Python user experience, visualizing simulations or data, software packaging (e.g. binary packages or Docker containers), or documentation. This project is for a student who has been using ns-3 for a while and has ideas on how to make it better during GSoC. We don't want to limit the scope of proposals here; we will consider any project ideas that improve ns-3 usability in some way (please explain to us why the usability improvement is important to users beyond yourself, and why you would argue for your particular solution, and of course describe how you plan to get it done during the timeframe of GSoC). Some project examples:
* Tools and scripts to conduct and manage data from a large number of simulation runs
* How to integrate a more Python-centric data flow and tools, such as [http://jupyter.org/ Jupyter Notebook] and [https://github.com/bloomberg/bqplot bqplot]
* Internal state visualization of Wi-Fi or LTE, such as the kind of plots generated by [http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.126.3791&rep=rep1&type=pdf Yavista]

==== L4/L3 routing improvement ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

At the moment, each packet in ns-3 is routed independently. Even though this is a good behaviour for routers, it is not for the source node (expecially for TCP). As a matter of fact, when a TCP connection is established, *all* its packets should be directed to the very same output interface. The same goes for UDP when the source address is forced to be a specific one.
The project idea is to modify the TCP and UDP stacks so that they can store the source address after the connection phase, and skip part of the routing process.
* ''Required Experience:'' C++, TCP, UDP
* ''Bonus Experience:'' IPv4 and IPv6 routing
* ''Interests:'' TCP and UDP
* ''Difficulty:'' medium
* ''Recommended reading:''
** [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1041 Bug 1041]

==== NetDevice up/down consistency and event chain ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella], Manoj Kumar Rana

There in no actual consistency among the different modules about how to handle Up/Down events (e.g., when a link is lost).
This prevents some "normal" behaviours from happening, e.g., the DHCP IP address renegotiation, MIP implementation, etc.
As a matter offact, one should expect that an IP interface would be declared as "down" when its NetDevice is down... but it isn't. The goal of this project is to fix this behavior, to update some NetDevices so that they use Up/Down events consistently, to provide the documentation about what is the standard behavior, and what NetDevices are actually implementing it in the right way.
* ''Required Experience:'' C++, NetDevices, Interface behavior
* ''Bonus Experience:'' NetDevice and IP behavior
* ''Interests:'' NetDevice and IP behavior
* ''Difficulty:'' medium

==== Wi-Fi mesh module upgrade ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

ns-3 Wi-Fi mesh module was written about 8 years ago, and is not completely up to date with the standard, nor does it work with newer Wi-Fi variants (802.11n/ac/ax). This project would prioritize making mesh module compatible with all variants of Wi-Fi and would align with the latest standard. Going further, some scenarios and scripts that align ns-3 simulations with how community networks are set up and configured would be helpful, such as guidance on how to configure rate controls and routing protocols (e.g. how to run OLSR on top of mesh).

* ''Required Experience:''C++, Wi-Fi and mesh understanding
* ''Interests:'' mesh networking
* ''Difficulty:'' Medium
* ''Recommended reading:'' mesh issues in the [https://www.nsnam.org/bugzilla/buglist.cgi?component=mesh&product=ns-3&query_format=advanced&resolution=--- tracker], and the mesh module documentation, and IEEE 802.11 standard

==== Direct Code Execution upgrade ====

Mentor: [mailto:mattator@gmail.com Matthieu Coudron]

ns-3 has an extension known as Direct Code Execution, which allows users to build C or C++-based applications, and open source (Linux, FreeBSD) kernels, into ns-3. However, support for the latest kernels (e.g. Linux kernel 4 series) and latest gcc versions has languished. We also could better integrate DCE with the main ns-3 tree. This project seeks a student interested in DCE, improving usability, and making it current with latest kernels and toolchains. The payoff of this type of project is very high since DCE makes available a lot of real-world models for use in ns-3. If you select this project idea, please engage with us on the developers list, and consider to take a look at solving one of the [https://www.nsnam.org/bugzilla/buglist.cgi?bug_status=__open__&content=&no_redirect=1&order=Importance&product=dce&query_format=specific open DCE issues in our tracker], for starters.
* ''Required Experience:'' good hacking skills on Linux, C, C++, Python
* ''Difficulty:'' Hard.
* ''For more information:'' https://www.nsnam.org/overview/projects/direct-code-execution/dce-1-9/

==== Freshen ns-3/Click integration ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

ns-3 and [https://github.com/kohler/click Click modular routing] were first integrated in an [https://www.nsnam.org/wiki/GSOC2010Click ns-3 GSoC project] from 2010. We seek a student interested in the following tasks:

* Since 2010, Ipv4L3Protocol has continued to evolve, but Ipv4L3ClickProtocol has not kept pace with the changes. Also, IPv6 is not supported. Refactor Ipv4L3Protocol and Ipv4L3ClickProtocol (or delete Ipv4L3ClickProtocol altogether) so that the click-specific pieces are limited and can be maintained more easily.
** Current thoughts on this are that we would like to modify the approach. It would be nice for Click to run on ns-3 in a manner that is as close as possible to its working outside simulation (raw sockets + tun/tap devices). This will hopefully allow us to delete IPv4L3ClickProtocol and avoid needed ns-3 code to expect Click to provide a routing table. ns-3 traffic generators should then be able to send packets to an ns-3 equivalent of a tun/tap device (which doesn't presently exist), have packets show up in Click, and then get Click to push those packets directly to an interface using raw sockets from inside ns-3.
* There was an [https://www.nsnam.org/wiki/NSOC2011ClickMac/MidTermReport ns-3 2011 summer project] (not part of GSoC, but a follow-on project) to try to finish the integration with ClickMac. We'd like to update it, finish it off, and merge it with ns-3-dev. Some brief discussion was here: https://codereview.appspot.com/4890044/
** The blocking issue at the time was in the Wi-Fi module; the changes in radiotap and frame injection over monitor mode, which Click needed, were not finished (accepted).
* Anything else that a student thinks would be useful to support regarding click and ns-3 integration. Consider to review in the recent literature (see Google Scholar) how Click is now being used for research, and think about then what might be research-driven priorities for support in ns-3. Provide evidence (citations) in your application.

The list is not exhaustive and not limiting. I.e., the candidate can propose other points and/or concentrate on a specific subset.

* ''Required Experience:'' C++
* ''Bonus Experience:'' IPv4, IPv6, Click.
* ''Interests:'' Software integration.
* ''Difficulty:'' Medium.

==== User-friendly internet-apps ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

Ping is a ubiquitous application for reachability and latency measurements. ns-3 already has a ping model (the v4ping.cc and ping6.cc). However, a user-friendly API could still be added. It is not straightforward to configure an ns-3 program to do in a single statement, for example, "Ping the IP address W.X.Y.Z from node 0 between times 5 and 50 seconds in my program, and save the output in traditional format to the file <filename.txt>", or to configure the many options found in the ping man page. This project is therefore not about developing brand new features as much as it is about making ping super-easy to use with a great API. Have a look at how ns-3 programs are written, and tell us what kind of API makes sense to you, and why, and how you would go about prioritizing its implementation. If ping is solved very early, the project can follow the same pattern for one or two more applications (e.g. netperf, iperf, etc.).

* ''Required Experience:''C++
* ''Interests:'' Network performance management
* ''Difficulty:'' Medium
* ''Recommended reading:''

==== nam upgrade and support for ns-3 ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

[http://www.isi.edu/nsnam/nam/ nam] is a Tcl/Tk-based animator for ns-2. Some example videos are found at [https://www.youtube.com/results?search_query=nam+network+animator YouTube]. nam has been functionally replaced in many ways by [https://www.nsnam.org/wiki/NetAnim NetAnim], but it still has some attractive features and might make a complementary animation tool for ns-3. In fact, someone did a proof-of-concept support of nam for ns-3 many years ago: http://www.nsnam.org/contributed/ns-3-nam.tar.bz2. This project would involve upgrading nam support to the latest Tcl/Tk release series (8.6) and then using the existing ns-3 trace system to generate nam output files such as in ns-2, and documenting and testing the results, including some demonstration videos.

* ''Required Experience:''C++, Tcl/Tk also preferred
* ''Interests:'' Network visualization/animation
* ''Difficulty:'' Medium
* ''Recommended reading:''
** the links listed above

==== ns-2 ports to ns-3 ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani]

[http://www.isi.edu/nsnam/ns/ ns-2] is the predecessor to ns-3, but some popular models still exist in ns-2 and are not yet ported to ns-3. Google Scholar can be used to find topics for which people still are publishing papers using ns-2. This project idea is for someone who is fond of some feature or model found in ns-2 but not in ns-3. A successful application of this type will make a good case that the port is still relevant to network research, that people are using ns-2 due to this model, and will describe the technical approach that is planned to make the port (e.g. how OTcl default variables will be ported to ns-3). Please note that the networking relevance is very important part of the application; if you propose to port some feature of ns-2 that is dated or unlikely to be of much interest because its applicability is very narrow, your proposal will not be selected.

* ''Required Experience:''C++, ns-2 also preferred
* ''Difficulty:'' Low to medium
* ''Recommended reading:''
** ns-2 and ns-3 manuals

==== TCP testing and alignment ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani], [mailto:natale.patriciello@gmail.com Natale Patriciello]

ns-3 needs good TCP models that align with real implementations, or that have documented differences. In particular, does ns-3 TCP's slow start and congestion avoidace perform like a real implementation, including common variants found in the field (CUBIC, DCTCP), and ones under development (TCP Prague, BBR). The project should also produce regression tests. We envision that this project will consist of setting up ns-3 in emulation mode to test operation of its implementation against real implementations, in different impairment environments, documenting the results, and figuring out how to take the ns-3 results and generate regression tests.

* ''Required Experience:''C++, TCP
* ''Difficulty:'' Medium
* ''Recommended reading:''
** Similar FreeBSD test suite: https://wiki.freebsd.org/SummerOfCode2016/TCP-IP-RegressionTestSuite
** https://wiki.linuxfoundation.org/networking/tcp_testing

==== TCP analysis ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani], [mailto:natale.patriciello@gmail.com Natale Patriciello]

This project is not about developing new TCP variants, but about developing a TCP analysis capability that is user-friendly and produces output similar to (perhaps integrates with?) tools such as [http://research.protocollabs.com/captcp/ captcp], [http://www.wireshark.org Wireshark TCP analysis], [http://www.tcptrace.org/ tcptrace], [http://tstat.polito.it/ Tstat], or other similar tools. An important part of your application will be a description of how a user will enable it in a user program, and some description of how it will be implemented.

As an example, consider providing the user with the ability to auto-generate plots of throughput evolution, congestion window evolution, etc. over time, for a pair of 4-tuples where the 4-tuples may contain wild cards or regular expressions. For instance, the user specifies "10.0.0.1:*" and "192.168.0.1:80", and if there are three connections in the simulation from 10.0.0.1 to that specific IP address and port, then three sets of time-series plots are generated and labelled appropriately.

* ''Required Experience:''C++, TCP
* ''Difficulty:'' Medium
* ''Recommended reading:''
** ns-2 and ns-3 manuals

==== 802.15.4 Bootstrap ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The lr-wpan model is an 802.15.4 PHY and MAC model currently in development. The model is able to simulate an 802.15.4 network in ad-hoc mode, much like Contiki-os nodes do. An useful extension is to fully support the node bootstrap phase, including node association and beacon request/reply. The goal of the project is to enhance the lr-wpan module so to use beacons in the bootstrap phase along with network scanning and pan-id resolution for in-range coordinators.
* ''Required Experience:'' C++, WSN
* ''Bonus Experience:'' 802.15.4 standard
* ''Interests:'' WSN
* ''Difficulty:'' medium
* ''Recommended reading:''
** [http://standards.ieee.org/getieee802/download/802.15.4-2011.pdf 802.15.4 Standard]

==== 802.15.4 Beacon-enabled mode ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The lr-wpan model is an 802.15.4 PHY and MAC model currently in development. The model is able to simulate an 802.15.4 network in ad-hoc mode, much like Contiki-os nodes do. Unlike Contiki-os, the model could benefit from supporting beacon-enabled mode of operation. The beacon-enabled mode is a fully slotted transmission mode, with guaranteed slots and bound performances, unlike the ad-hoc mode. This is especially important because the L3 routing protocols might be strongly affected by the lower-layer topology. Hence it is of paramount importance to be able to simulate both in ns-3. The goal of the project is to develop the new beacon-enabled MAC layer for the lr-wpan module.
* ''Required Experience:'' C++, WSN
* ''Bonus Experience:'' 802.15.4 standard
* ''Interests:'' WSN
* ''Difficulty:'' medium/hard
* ''Recommended reading:''
** [http://standards.ieee.org/getieee802/download/802.15.4-2011.pdf 802.15.4 Standard]

==== DSR routing RFC compliance ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The DSR routing module is not compliant with the RFC 4728. This leads to a number of small issues, like simulation imprecision and impossibility to decode the messages with Wireshark.
The goal of the project is to enhance the current model and to make it RFC-compliant, eventually doing a code refectory where needed.
A possible enhancement over the base protocol could also be to include support for IPv6 in the implementation.
* ''Required Experience:'' C++
* ''Bonus Experience:'' DSR standard
* ''Interests:'' Ad-hoc routing
* ''Difficulty:'' medium
* ''Recommended reading:''
** [http://www6.ietf.org/rfc/rfc4728.txt RFC 4728]

==== Enable IPv6 support for Ad hoc Routing Protocols in ns-3 ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani]

ns-3 contains models for proactive (DSDV and OLSR) and reactive (AODV and DSR) ad hoc routing protocols. However, these models are IPv4-only and do not provide support of IPv6 addressing. This project aims to enable IPv6 support for ad hoc routing protocols in ns-3, mainly for AODV and DSR. There are out-of-tree implementations of OLSR and DSDV that provide support for IPv6 addressing, and can be used as references to get started with this project.
An important point of the implementation should be code duplicate minimization, in order to have the minimize maintenance efforts.
Note: Enabling IPv6 support for these protocols is not a matter of simply changing out an IPv4-formatted address for an IPv6-formatted address. The IPv6 addressing architecture emphasizes scoping much more than does IPv4 (RFC 4007). Please suggest in your application how IPv6 address configuration (and possibly auto-configuration?) and address scopes (e.g. link-local vs. global) should be used in these protocols. Consulting the RFCs is highly recommended.'

* ''Required Experience:'' Fundamentals of IPv6 addressing, C++ programming.
* ''Bonus Experience:'' Familiarity with AODV and DSR implementations in ns-3
* ''Interests:'' Ad hoc routing
* ''Difficulty:'' Medium.
* ''Recommended reading:''
** [https://www.nsnam.org/docs/models/html/ipv6.html IPv6 model in ns-3]
** [https://www.nsnam.org/docs/models/html/aodv.html AODV model in ns-3]
** [https://www.nsnam.org/docs/models/html/dsr.html DSR model in ns-3]
** [https://www.nsnam.org/workshops/wns3-2016/posters/IPv6-support-for-OLSR.pdf IPv6 Support for OLSR in ns-3]

==== Data collection and statistics framework extension ====

Mentors: [mailto:dizhizhou@hotmail.com Dizhi Zhou]

The goal of this project is to extend and add more functionalities on ns-3 data collection and statistics framework (source code:ns-3.27/src/stats/) which was added in ns-3.18. The model was implemented based on the ns-3 tracing system. It has two major functions. 1) retrieve data from multiple ns-3 trace sources and then recalculate/transform the data into a user-defined format. However, not all the trace source types are supported. 2) use a data collector to calculate some useful statistics from a ns-3 trace source (e.g. max and min of the trace value). However, only supports counter and min/max data collectors are supported today. In order to make the model more useful, more trace source types, output formats and collectors need to be added.

A parallel project of ns-3, named sns3, proposed an enhancement on this model in 2016. But the patch was not merged to the official release yet. Student may use this patch as a reference for their proposals. Some sample ideas are listed below.
* ''Help to merge sns3 statistic enhancement to ns-3.
* ''Add more trace types
* ''Add more collectors. Ideally, the statistic calculation method should be configurable in the script so that people don’t need to add new collectors when they have any new requirement.
* ''More output format types: excel, MySql, matplotlib, R, Matlab, more picture formats, etc.
* ''Improve documentation and add more example scripts.

The list is not exhaustive and not limiting. Any new ideas in this area are welcome.
* ''Required Experience:'' C++ programming.
* ''Bonus Experience:'' Proficiency with open source data handling software (e.g. R, matplotlib, SQLite, gnuplot)
* ''Difficulty:'' Medium.
* ''Recommended reading:''
** [https://www.nsnam.org/documentation/ Data collection and trace chapters in ns-3 tutorial/manual/model library]
** [https://codereview.appspot.com/318800043/ Statistic model enhancement code review from sns3 project]

==== Persistent and Semi-Persistent Scheduling inside LTE module ====

Mentors: [mailto:natale.patriciello@gmail.com Natale Patriciello], [mailto:sandra.lagen@cttc.cat Sandra Lagen]

The goal of this project is to implement Semi-Persistent Scheduling (SPS) scheme in the ns-3 LTE module. SPS scheme is enabled in 4G LTE, as well as in 5G, in order to save L1/L2 (layer 1/layer 2) control signaling and reduce resource overhead for some periodic and predictable traffic, such as voice over IP (VoIP) and traffic from sensors/IoT devices. Currently, in ns-3 LTE, only Dynamic Scheduling (DS) scheme is implemented, for which the scheduling decisions are dynamically signaled on L1/L2 control to indicate the allocated resources. Differently, in SPS, only the first scheduling assignment is signaled on L1/L2, and the subsequent transmissions use the same resources with a preconfigured interval, thus reducing L1/L2 overhead. In particular, SPS periodicity is configured by RRC, and then activation is signaled through the downlink control information (DCI), both for downlink and uplink SPS. The idea of this project is to extend RRC parameters, and DCI formats, to enable SPS scheme, and to update the MAC scheduler (L2) to enable both SPS and DS schemes for different traffic simultaneously. The later requires, among others, a memory in the scheduler, so as not to allocate resources for DS that are already scheduled for SPS.

* ''Required Experience:'' C++, LTE understanding
* ''Bonus Experience:'' Familiarity with lte module
* ''Interests:'' LTE scheduling (MAC layer)
* ''Difficulty:'' Medium.

==== Structured logging support ====

Mentors: [mailto:krotov@iitp.ru Alexander Krotov], ?

Sometimes an experiment with a hard to find bug takes a lot of time to run, so it may be desirable to collect as much information as possible and process it later, without adding traces and running experiment again multiple times.

Existing NS-3 logging framework does not support structured logging. It is only capable of printing text messages, which are hard to process automatically. In fact, [https://www.nsnam.org/docs/manual/html/logging.html NS-3 manual] even contains a warning:
<blockquote>
The project makes no guarantee about whether logging output will remain the same over time. Users are cautioned against building simulation output frameworks on top of logging code, as the output and the way the output is enabled may change over time.
</blockquote>

Currently logs often lack context information, such as MAC addresses, node IDs etc. Even if the required information is present, extracting it from text messages is error-prone, and message format may change from version to version even when the required data is still available. As a result, it is often easier to resort to installing traces and adding conditionals to the NS-3 code, recompiling the code and re-running experiments.

Structured logging, sometimes called semantic logging, is an approach that solves the problem of logs not being machine-readable.

For example, instead of writing
<pre>
NS_LOG_LOGIC ("Route to " << m_endPoint->GetPeerAddress () << " does not exist");
</pre>
it will be possible to write something like
<pre>
NS_LOG_LOGIC ("Route to {peer_address} does not exist",
"peer_address", m_endPoint->GetPeerAddress (),
"id", "route_not_exist");
</pre>

When used in text mode, the logging framework will output messages as usual. In addition, it will be able to store messages as dictionaries, for example in [http://jsonlines.org/ JSON Lines], [http://cbor.io/ some binary format] or a [https://docs.mongodb.com/ecosystem/use-cases/storing-log-data/ database].

The message above could be represented as
<pre>
{
"message": "Route to {peer_address} does not exist",
"peer_address": {"type": "ipv4", "192.168.1.1"},
"id": "route_not_exist"
...
}
</pre>
In addition, messages need to contain some context, extracted from object <code>this</code>, object identifier (its pointer) and timestamp.

The goal of this project is to
* Add API to serialize NS-3 object to dictionaries.
* Implement structured logging framework in the <code>core</code> module.
* Implement at least text and JSON output, extensible to add more output formats later.
* Add structured logging support to at least some modules, e.g. <code>applications</code>. It should be possible to incrementally switch to structured logging support later.

There are hardly any C++ structured logging frameworks. There is a https://github.com/kevincox/sog, which is abandoned and uses Apache 2.0 license, that is incompatible to NS-3 license (GPLv2). As a result, it will probably be required to implement the whole framework from scratch. Structured logging frameworks for other languages, such as https://serilog.net/, can be used for inspiration.

* ''Required Experience:'' C++
* ''Difficulty:'' medium

[[Category:GSoC]]

GSOC2019Projects

2019-02-05T16:06:56Z

Krotov: /* Structured logging support */

{{TOC}}

This page contains 2019 Google Summer of Code project ideas for ns-3.

'''Important note:''' Google has not selected participating open source projects yet; we are only in the application phase.

* [http://www.google-melange.com/gsoc/document/show/gsoc_program/google/gsoc2015/help_page GSoC Frequently Asked Questions]
* [[GSOC2018StudentGuide |ns-3's 2018 GSoC Student guide]]
* [http://en.flossmanuals.net/GSoCStudentGuide/ GSoC student guide (not ns-3 specific)]
* [[GSOC2018StudentApplicationTemplate |2018 GSoC Student application template]]
* [[GSOCMentorGuide | ns-3's GSoC Mentor guide]]
* [http://en.flossmanuals.net/gsoc-mentoring/ GSoC Mentor guide (not ns-3 specific)]
* [[GSOCSelectionProcess | GSoC Student Selection Process]]
* ''Get in contact with the ns-3 team'': [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers mailing list] | ''chat'' https://ns-3.zulipchat.com/

=== About the ns-3 project ===

ns-3 is a discrete-event network simulator, with a particular emphasis on network research and education.

Users of ns-3 can construct simulations of computer networks using models of traffic generators, protocols such as TCP/IP, and devices and channels such as WiFi, and analyze or visualize the results. Simulation plays a vital role in the research and education process, because of the ability for simulations to obtain reproducible results (particularly for wireless protocol design), scale to large networks, and study systems that have not yet been implemented. A particular emphasis in ns-3 is the high degree of realism in the models (including frameworks for real application and kernel code) and integration of the tool with virtual machine environments and testbeds; we view that researchers need to move more effortlessly between simulation, testbeds, and live experiments, and ns-3 is designed to facilitate that.

Google Summer of Code organizational admins for ns-3 are [mailto:tpecorella@mac.com Tommaso Pecorella] and [mailto:tomh@tomh.org Tom Henderson]; contact them with any questions. They also hang out on [https://ns-3.zulipchat.com Zulip]. The project has participated in past GSoCs during 2008-10, 2012-15, and 2017-18.

Mentors will be paired with students based on the projects that are selected. Mentors from companies are welcome, if the employer will permit the mentor sufficient time to perform the mentoring. Prospective mentors should notify Tom Henderson or Tommaso Pecorella of interest. Mentors familiar with ns-3 development practices will be preferred, to improve the chances of student code merge. In 2019, we are going to be seeking two-person mentoring teams for projects, to help with the mentoring workload and bring more expertise.

=== Students: how to participate ===

For students interested in applying to ns-3 for GSOC, first wait to see if ns-3 will be selected. If so, then go through the following list to get started:
* Read the official [http://en.flossmanuals.net/GSoCStudentGuide/ GSoC student guide].
* Read [[GSOC2018StudentGuide |ns-3's GSoC Student guide]].
* Look through our [[#Project Ideas]] below to see if you find a project that interests you.
* Review the [http://www.nsnam.org/ns-3-29/documentation/ns-3 tutorial] thoroughly, if you have not already done so.
* Look through the [[GSOC2018StudentApplicationTemplate |GSoC Student application template]] to start preparing your proposal.
* Next, proceed to get in touch with the developers on the mailing list and refine your proposal.
* In parallel, make sure you prepare a patch as per the [[GSOC2018PatchRequirement | Patch Requirement Guidelines]] (to be revised). Your application to ns-3 will not be considered if you do not fulfill this requirement.

Below is a list of [[#Project Ideas]] proposed by the ns-3 team for Google Summer of Code 2019. Please note that these ideas are not limited to GSoC; anyone is welcome to work on them. Please email the [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers list] if you have a different idea that you'd like to work on, to see if a mentor may be interested. Applicants are encouraged to look over this list, pick one that especially interests them, think about it, and discuss potential approaches on the [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers list]. Previous experience with the Google Summer of Code programmes suggest that the more you discuss and refine your proposal on the mailing list beforehand, the stronger the proposal it will develop into, and the higher your chances of being accepted into the programme.

<blockquote>
Each project idea within a particular priority has been tagged with the following properties:
* ''Required Experience:'' Languages, concepts, or packages with which applicants must be familiar.
* ''Bonus Experience:'' Other experience or familiarity which would be greatly helpful to applicants for this project.
* ''Interests:'' Areas of particular relevance to this project, and an indicator of where successful students might apply their experiences coming out of this project.
* ''Difficulty:'' easy, medium or difficult
* ''Recommended reading:'' pointers to documentation, papers, specific bugs, etc.

Note that all of the projects require some experience and comfort with C++. Project ideas for which C++ is noted as a required experience will require more and deeper familiarity with the language. A similar notion applies to computer networking, BSD sockets, etc: Familiarity is strongly preferred, but is not required except where explicitly noted due to the topic being more advanced in that regard.
</blockquote>

=== Mentors: how to participate ===

The ns-3 project is open to the proposal of new project ideas by developers interested in being a GSoC mentor. For mentors who're adding project ideas to the list below, please ensure that:

* The projects are sized such that there can be a code merge by the end of the coding period. The scope of the project should be such that it is very difficult to not have a code merge by the end of the summer.
* The proposed projects are not too open-ended. That is, if the deliverables or a clear path to the same are not well understood, it is better kept outside GSOC.
* There should be a clear merge path to one of the main project code repositories (ns-3-dev, ns-3-dce, bake) by the end of the summer, either because the patches directly apply to these repositories, or because they apply to an ns-3 module that is in the process of being merged with ns-3-dev.

== Project Ideas ==

'''Note to students:''' These ideas are not listed in any priority order. The list of mentors for 2019 includes Mohit Tahiliani, Alexander Krotov, Abhijith Anilkumar, Ankit Deepak, Dizhi Zhou, and Gabriel Arrobo, and others are in discussion.

==== Usability improvements ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], Dizhi Zhou, others TBD

Usability of ns-3 can always be improved, whether it is help with building simulations, running simulation campaigns, using the ns-3 C++ API, improving the Python user experience, visualizing simulations or data, software packaging (e.g. binary packages or Docker containers), or documentation. This project is for a student who has been using ns-3 for a while and has ideas on how to make it better during GSoC. We don't want to limit the scope of proposals here; we will consider any project ideas that improve ns-3 usability in some way (please explain to us why the usability improvement is important to users beyond yourself, and why you would argue for your particular solution, and of course describe how you plan to get it done during the timeframe of GSoC). Some project examples:
* Tools and scripts to conduct and manage data from a large number of simulation runs
* How to integrate a more Python-centric data flow and tools, such as [http://jupyter.org/ Jupyter Notebook] and [https://github.com/bloomberg/bqplot bqplot]
* Internal state visualization of Wi-Fi or LTE, such as the kind of plots generated by [http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.126.3791&rep=rep1&type=pdf Yavista]

==== L4/L3 routing improvement ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

At the moment, each packet in ns-3 is routed independently. Even though this is a good behaviour for routers, it is not for the source node (expecially for TCP). As a matter of fact, when a TCP connection is established, *all* its packets should be directed to the very same output interface. The same goes for UDP when the source address is forced to be a specific one.
The project idea is to modify the TCP and UDP stacks so that they can store the source address after the connection phase, and skip part of the routing process.
* ''Required Experience:'' C++, TCP, UDP
* ''Bonus Experience:'' IPv4 and IPv6 routing
* ''Interests:'' TCP and UDP
* ''Difficulty:'' medium
* ''Recommended reading:''
** [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1041 Bug 1041]

==== NetDevice up/down consistency and event chain ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella], Manoj Kumar Rana

There in no actual consistency among the different modules about how to handle Up/Down events (e.g., when a link is lost).
This prevents some "normal" behaviours from happening, e.g., the DHCP IP address renegotiation, MIP implementation, etc.
As a matter offact, one should expect that an IP interface would be declared as "down" when its NetDevice is down... but it isn't. The goal of this project is to fix this behavior, to update some NetDevices so that they use Up/Down events consistently, to provide the documentation about what is the standard behavior, and what NetDevices are actually implementing it in the right way.
* ''Required Experience:'' C++, NetDevices, Interface behavior
* ''Bonus Experience:'' NetDevice and IP behavior
* ''Interests:'' NetDevice and IP behavior
* ''Difficulty:'' medium

==== Wi-Fi mesh module upgrade ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

ns-3 Wi-Fi mesh module was written about 8 years ago, and is not completely up to date with the standard, nor does it work with newer Wi-Fi variants (802.11n/ac/ax). This project would prioritize making mesh module compatible with all variants of Wi-Fi and would align with the latest standard. Going further, some scenarios and scripts that align ns-3 simulations with how community networks are set up and configured would be helpful, such as guidance on how to configure rate controls and routing protocols (e.g. how to run OLSR on top of mesh).

* ''Required Experience:''C++, Wi-Fi and mesh understanding
* ''Interests:'' mesh networking
* ''Difficulty:'' Medium
* ''Recommended reading:'' mesh issues in the [https://www.nsnam.org/bugzilla/buglist.cgi?component=mesh&product=ns-3&query_format=advanced&resolution=--- tracker], and the mesh module documentation, and IEEE 802.11 standard

==== Direct Code Execution upgrade ====

Mentor: [mailto:mattator@gmail.com Matthieu Coudron]

ns-3 has an extension known as Direct Code Execution, which allows users to build C or C++-based applications, and open source (Linux, FreeBSD) kernels, into ns-3. However, support for the latest kernels (e.g. Linux kernel 4 series) and latest gcc versions has languished. We also could better integrate DCE with the main ns-3 tree. This project seeks a student interested in DCE, improving usability, and making it current with latest kernels and toolchains. The payoff of this type of project is very high since DCE makes available a lot of real-world models for use in ns-3. If you select this project idea, please engage with us on the developers list, and consider to take a look at solving one of the [https://www.nsnam.org/bugzilla/buglist.cgi?bug_status=__open__&content=&no_redirect=1&order=Importance&product=dce&query_format=specific open DCE issues in our tracker], for starters.
* ''Required Experience:'' good hacking skills on Linux, C, C++, Python
* ''Difficulty:'' Hard.
* ''For more information:'' https://www.nsnam.org/overview/projects/direct-code-execution/dce-1-9/

==== Freshen ns-3/Click integration ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

ns-3 and [https://github.com/kohler/click Click modular routing] were first integrated in an [https://www.nsnam.org/wiki/GSOC2010Click ns-3 GSoC project] from 2010. We seek a student interested in the following tasks:

* Since 2010, Ipv4L3Protocol has continued to evolve, but Ipv4L3ClickProtocol has not kept pace with the changes. Also, IPv6 is not supported. Refactor Ipv4L3Protocol and Ipv4L3ClickProtocol (or delete Ipv4L3ClickProtocol altogether) so that the click-specific pieces are limited and can be maintained more easily.
** Current thoughts on this are that we would like to modify the approach. It would be nice for Click to run on ns-3 in a manner that is as close as possible to its working outside simulation (raw sockets + tun/tap devices). This will hopefully allow us to delete IPv4L3ClickProtocol and avoid needed ns-3 code to expect Click to provide a routing table. ns-3 traffic generators should then be able to send packets to an ns-3 equivalent of a tun/tap device (which doesn't presently exist), have packets show up in Click, and then get Click to push those packets directly to an interface using raw sockets from inside ns-3.
* There was an [https://www.nsnam.org/wiki/NSOC2011ClickMac/MidTermReport ns-3 2011 summer project] (not part of GSoC, but a follow-on project) to try to finish the integration with ClickMac. We'd like to update it, finish it off, and merge it with ns-3-dev. Some brief discussion was here: https://codereview.appspot.com/4890044/
** The blocking issue at the time was in the Wi-Fi module; the changes in radiotap and frame injection over monitor mode, which Click needed, were not finished (accepted).
* Anything else that a student thinks would be useful to support regarding click and ns-3 integration. Consider to review in the recent literature (see Google Scholar) how Click is now being used for research, and think about then what might be research-driven priorities for support in ns-3. Provide evidence (citations) in your application.

The list is not exhaustive and not limiting. I.e., the candidate can propose other points and/or concentrate on a specific subset.

* ''Required Experience:'' C++
* ''Bonus Experience:'' IPv4, IPv6, Click.
* ''Interests:'' Software integration.
* ''Difficulty:'' Medium.

==== User-friendly internet-apps ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

Ping is a ubiquitous application for reachability and latency measurements. ns-3 already has a ping model (the v4ping.cc and ping6.cc). However, a user-friendly API could still be added. It is not straightforward to configure an ns-3 program to do in a single statement, for example, "Ping the IP address W.X.Y.Z from node 0 between times 5 and 50 seconds in my program, and save the output in traditional format to the file <filename.txt>", or to configure the many options found in the ping man page. This project is therefore not about developing brand new features as much as it is about making ping super-easy to use with a great API. Have a look at how ns-3 programs are written, and tell us what kind of API makes sense to you, and why, and how you would go about prioritizing its implementation. If ping is solved very early, the project can follow the same pattern for one or two more applications (e.g. netperf, iperf, etc.).

* ''Required Experience:''C++
* ''Interests:'' Network performance management
* ''Difficulty:'' Medium
* ''Recommended reading:''

==== nam upgrade and support for ns-3 ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

[http://www.isi.edu/nsnam/nam/ nam] is a Tcl/Tk-based animator for ns-2. Some example videos are found at [https://www.youtube.com/results?search_query=nam+network+animator YouTube]. nam has been functionally replaced in many ways by [https://www.nsnam.org/wiki/NetAnim NetAnim], but it still has some attractive features and might make a complementary animation tool for ns-3. In fact, someone did a proof-of-concept support of nam for ns-3 many years ago: http://www.nsnam.org/contributed/ns-3-nam.tar.bz2. This project would involve upgrading nam support to the latest Tcl/Tk release series (8.6) and then using the existing ns-3 trace system to generate nam output files such as in ns-2, and documenting and testing the results, including some demonstration videos.

* ''Required Experience:''C++, Tcl/Tk also preferred
* ''Interests:'' Network visualization/animation
* ''Difficulty:'' Medium
* ''Recommended reading:''
** the links listed above

==== ns-2 ports to ns-3 ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani]

[http://www.isi.edu/nsnam/ns/ ns-2] is the predecessor to ns-3, but some popular models still exist in ns-2 and are not yet ported to ns-3. Google Scholar can be used to find topics for which people still are publishing papers using ns-2. This project idea is for someone who is fond of some feature or model found in ns-2 but not in ns-3. A successful application of this type will make a good case that the port is still relevant to network research, that people are using ns-2 due to this model, and will describe the technical approach that is planned to make the port (e.g. how OTcl default variables will be ported to ns-3). Please note that the networking relevance is very important part of the application; if you propose to port some feature of ns-2 that is dated or unlikely to be of much interest because its applicability is very narrow, your proposal will not be selected.

* ''Required Experience:''C++, ns-2 also preferred
* ''Difficulty:'' Low to medium
* ''Recommended reading:''
** ns-2 and ns-3 manuals

==== TCP testing and alignment ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani], [mailto:natale.patriciello@gmail.com Natale Patriciello]

ns-3 needs good TCP models that align with real implementations, or that have documented differences. In particular, does ns-3 TCP's slow start and congestion avoidace perform like a real implementation, including common variants found in the field (CUBIC, DCTCP), and ones under development (TCP Prague, BBR). The project should also produce regression tests. We envision that this project will consist of setting up ns-3 in emulation mode to test operation of its implementation against real implementations, in different impairment environments, documenting the results, and figuring out how to take the ns-3 results and generate regression tests.

* ''Required Experience:''C++, TCP
* ''Difficulty:'' Medium
* ''Recommended reading:''
** Similar FreeBSD test suite: https://wiki.freebsd.org/SummerOfCode2016/TCP-IP-RegressionTestSuite
** https://wiki.linuxfoundation.org/networking/tcp_testing

==== TCP analysis ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani], [mailto:natale.patriciello@gmail.com Natale Patriciello]

This project is not about developing new TCP variants, but about developing a TCP analysis capability that is user-friendly and produces output similar to (perhaps integrates with?) tools such as [http://research.protocollabs.com/captcp/ captcp], [http://www.wireshark.org Wireshark TCP analysis], [http://www.tcptrace.org/ tcptrace], [http://tstat.polito.it/ Tstat], or other similar tools. An important part of your application will be a description of how a user will enable it in a user program, and some description of how it will be implemented.

As an example, consider providing the user with the ability to auto-generate plots of throughput evolution, congestion window evolution, etc. over time, for a pair of 4-tuples where the 4-tuples may contain wild cards or regular expressions. For instance, the user specifies "10.0.0.1:*" and "192.168.0.1:80", and if there are three connections in the simulation from 10.0.0.1 to that specific IP address and port, then three sets of time-series plots are generated and labelled appropriately.

* ''Required Experience:''C++, TCP
* ''Difficulty:'' Medium
* ''Recommended reading:''
** ns-2 and ns-3 manuals

==== 802.15.4 Bootstrap ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The lr-wpan model is an 802.15.4 PHY and MAC model currently in development. The model is able to simulate an 802.15.4 network in ad-hoc mode, much like Contiki-os nodes do. An useful extension is to fully support the node bootstrap phase, including node association and beacon request/reply. The goal of the project is to enhance the lr-wpan module so to use beacons in the bootstrap phase along with network scanning and pan-id resolution for in-range coordinators.
* ''Required Experience:'' C++, WSN
* ''Bonus Experience:'' 802.15.4 standard
* ''Interests:'' WSN
* ''Difficulty:'' medium
* ''Recommended reading:''
** [http://standards.ieee.org/getieee802/download/802.15.4-2011.pdf 802.15.4 Standard]

==== 802.15.4 Beacon-enabled mode ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The lr-wpan model is an 802.15.4 PHY and MAC model currently in development. The model is able to simulate an 802.15.4 network in ad-hoc mode, much like Contiki-os nodes do. Unlike Contiki-os, the model could benefit from supporting beacon-enabled mode of operation. The beacon-enabled mode is a fully slotted transmission mode, with guaranteed slots and bound performances, unlike the ad-hoc mode. This is especially important because the L3 routing protocols might be strongly affected by the lower-layer topology. Hence it is of paramount importance to be able to simulate both in ns-3. The goal of the project is to develop the new beacon-enabled MAC layer for the lr-wpan module.
* ''Required Experience:'' C++, WSN
* ''Bonus Experience:'' 802.15.4 standard
* ''Interests:'' WSN
* ''Difficulty:'' medium/hard
* ''Recommended reading:''
** [http://standards.ieee.org/getieee802/download/802.15.4-2011.pdf 802.15.4 Standard]

==== DSR routing RFC compliance ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The DSR routing module is not compliant with the RFC 4728. This leads to a number of small issues, like simulation imprecision and impossibility to decode the messages with Wireshark.
The goal of the project is to enhance the current model and to make it RFC-compliant, eventually doing a code refectory where needed.
A possible enhancement over the base protocol could also be to include support for IPv6 in the implementation.
* ''Required Experience:'' C++
* ''Bonus Experience:'' DSR standard
* ''Interests:'' Ad-hoc routing
* ''Difficulty:'' medium
* ''Recommended reading:''
** [http://www6.ietf.org/rfc/rfc4728.txt RFC 4728]

==== Enable IPv6 support for Ad hoc Routing Protocols in ns-3 ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani]

ns-3 contains models for proactive (DSDV and OLSR) and reactive (AODV and DSR) ad hoc routing protocols. However, these models are IPv4-only and do not provide support of IPv6 addressing. This project aims to enable IPv6 support for ad hoc routing protocols in ns-3, mainly for AODV and DSR. There are out-of-tree implementations of OLSR and DSDV that provide support for IPv6 addressing, and can be used as references to get started with this project.
An important point of the implementation should be code duplicate minimization, in order to have the minimize maintenance efforts.
Note: Enabling IPv6 support for these protocols is not a matter of simply changing out an IPv4-formatted address for an IPv6-formatted address. The IPv6 addressing architecture emphasizes scoping much more than does IPv4 (RFC 4007). Please suggest in your application how IPv6 address configuration (and possibly auto-configuration?) and address scopes (e.g. link-local vs. global) should be used in these protocols. Consulting the RFCs is highly recommended.'

* ''Required Experience:'' Fundamentals of IPv6 addressing, C++ programming.
* ''Bonus Experience:'' Familiarity with AODV and DSR implementations in ns-3
* ''Interests:'' Ad hoc routing
* ''Difficulty:'' Medium.
* ''Recommended reading:''
** [https://www.nsnam.org/docs/models/html/ipv6.html IPv6 model in ns-3]
** [https://www.nsnam.org/docs/models/html/aodv.html AODV model in ns-3]
** [https://www.nsnam.org/docs/models/html/dsr.html DSR model in ns-3]
** [https://www.nsnam.org/workshops/wns3-2016/posters/IPv6-support-for-OLSR.pdf IPv6 Support for OLSR in ns-3]

==== Data collection and statistics framework extension ====

Mentors: [mailto:dizhizhou@hotmail.com Dizhi Zhou]

The goal of this project is to extend and add more functionalities on ns-3 data collection and statistics framework (source code:ns-3.27/src/stats/) which was added in ns-3.18. The model was implemented based on the ns-3 tracing system. It has two major functions. 1) retrieve data from multiple ns-3 trace sources and then recalculate/transform the data into a user-defined format. However, not all the trace source types are supported. 2) use a data collector to calculate some useful statistics from a ns-3 trace source (e.g. max and min of the trace value). However, only supports counter and min/max data collectors are supported today. In order to make the model more useful, more trace source types, output formats and collectors need to be added.

A parallel project of ns-3, named sns3, proposed an enhancement on this model in 2016. But the patch was not merged to the official release yet. Student may use this patch as a reference for their proposals. Some sample ideas are listed below.
* ''Help to merge sns3 statistic enhancement to ns-3.
* ''Add more trace types
* ''Add more collectors. Ideally, the statistic calculation method should be configurable in the script so that people don’t need to add new collectors when they have any new requirement.
* ''More output format types: excel, MySql, matplotlib, R, Matlab, more picture formats, etc.
* ''Improve documentation and add more example scripts.

The list is not exhaustive and not limiting. Any new ideas in this area are welcome.
* ''Required Experience:'' C++ programming.
* ''Bonus Experience:'' Proficiency with open source data handling software (e.g. R, matplotlib, SQLite, gnuplot)
* ''Difficulty:'' Medium.
* ''Recommended reading:''
** [https://www.nsnam.org/documentation/ Data collection and trace chapters in ns-3 tutorial/manual/model library]
** [https://codereview.appspot.com/318800043/ Statistic model enhancement code review from sns3 project]

==== Persistent and Semi-Persistent Scheduling inside LTE module ====

Mentors: [mailto:natale.patriciello@gmail.com Natale Patriciello], [mailto:sandra.lagen@cttc.cat Sandra Lagen]

The goal of this project is to implement Semi-Persistent Scheduling (SPS) scheme in the ns-3 LTE module. SPS scheme is enabled in 4G LTE, as well as in 5G, in order to save L1/L2 (layer 1/layer 2) control signaling and reduce resource overhead for some periodic and predictable traffic, such as voice over IP (VoIP) and traffic from sensors/IoT devices. Currently, in ns-3 LTE, only Dynamic Scheduling (DS) scheme is implemented, for which the scheduling decisions are dynamically signaled on L1/L2 control to indicate the allocated resources. Differently, in SPS, only the first scheduling assignment is signaled on L1/L2, and the subsequent transmissions use the same resources with a preconfigured interval, thus reducing L1/L2 overhead. In particular, SPS periodicity is configured by RRC, and then activation is signaled through the downlink control information (DCI), both for downlink and uplink SPS. The idea of this project is to extend RRC parameters, and DCI formats, to enable SPS scheme, and to update the MAC scheduler (L2) to enable both SPS and DS schemes for different traffic simultaneously. The later requires, among others, a memory in the scheduler, so as not to allocate resources for DS that are already scheduled for SPS.

* ''Required Experience:'' C++, LTE understanding
* ''Bonus Experience:'' Familiarity with lte module
* ''Interests:'' LTE scheduling (MAC layer)
* ''Difficulty:'' Medium.

==== Structured logging support ====

Mentors: [mailto:krotov@iitp.ru Alexander Krotov], ?

Sometimes an experiment with a hard to find bug takes a lot of time to run, so it may be desirable to collect as much information is possible and process it later, without adding traces and running experiment again multiple times.

Existing NS-3 logging framework does not support structured logging. It is only capable of printing text messages, which are hard to process automatically. In fact, [https://www.nsnam.org/docs/manual/html/logging.html NS-3 manual] even contains a warning:
<blockquote>
The project makes no guarantee about whether logging output will remain the same over time. Users are cautioned against building simulation output frameworks on top of logging code, as the output and the way the output is enabled may change over time.
</blockquote>

Currently logs often lack context information, such as MAC addresses, node IDs etc. Even if the required information is present, extracting it from text messages is error-prone, and message format may change from version to version even when the required data is still available. As a result, it is often easier to resort to installing traces and adding conditionals to the NS-3 code, recompiling the code and re-running experiments.

Structured logging, sometimes called semantic logging, is an approach that solves the problem of logs not being machine-readable.

For example, instead of writing
<pre>
NS_LOG_LOGIC ("Route to " << m_endPoint->GetPeerAddress () << " does not exist");
</pre>
it will be possible to write something like
<pre>
NS_LOG_LOGIC ("Route to {peer_address} does not exist",
"peer_address", m_endPoint->GetPeerAddress (),
"id", "route_not_exist");
</pre>

When used in text mode, the logging framework will output messages as usual. In addition, it will be able to store messages as dictionaries, for example in [http://jsonlines.org/ JSON Lines], [http://cbor.io/ some binary format] or a [https://docs.mongodb.com/ecosystem/use-cases/storing-log-data/ database].

The message above could be represented as
<pre>
{
"message": "Route to {peer_address} does not exist",
"peer_address": {"type": "ipv4", "192.168.1.1"},
"id": "route_not_exist"
...
}
</pre>
In addition, messages need to contain some context, extracted from object <code>this</code>, object identifier (its pointer) and timestamp.

The goal of this project is to
* Add API to serialize NS-3 object to dictionaries.
* Implement structured logging framework in the <code>core</code> module.
* Implement at least text and JSON output, extensible to add more output formats later.
* Add structured logging support to at least some modules, e.g. <code>applications</code>. It should be possible to incrementally switch to structured logging support later.

There are hardly any C++ structured logging frameworks. There is a https://github.com/kevincox/sog, which is abandoned and uses Apache 2.0 license, that is incompatible to NS-3 license (GPLv2). As a result, it will probably be required to implement the whole framework from scratch. Structured logging frameworks for other languages, such as https://serilog.net/, can be used for inspiration.

* ''Required Experience:'' C++
* ''Difficulty:'' medium

[[Category:GSoC]]

GSOC2019Projects

2019-02-05T16:05:09Z

Krotov: /* Project Ideas */ Add structured logging framework support task

{{TOC}}

This page contains 2019 Google Summer of Code project ideas for ns-3.

'''Important note:''' Google has not selected participating open source projects yet; we are only in the application phase.

* [http://www.google-melange.com/gsoc/document/show/gsoc_program/google/gsoc2015/help_page GSoC Frequently Asked Questions]
* [[GSOC2018StudentGuide |ns-3's 2018 GSoC Student guide]]
* [http://en.flossmanuals.net/GSoCStudentGuide/ GSoC student guide (not ns-3 specific)]
* [[GSOC2018StudentApplicationTemplate |2018 GSoC Student application template]]
* [[GSOCMentorGuide | ns-3's GSoC Mentor guide]]
* [http://en.flossmanuals.net/gsoc-mentoring/ GSoC Mentor guide (not ns-3 specific)]
* [[GSOCSelectionProcess | GSoC Student Selection Process]]
* ''Get in contact with the ns-3 team'': [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers mailing list] | ''chat'' https://ns-3.zulipchat.com/

=== About the ns-3 project ===

ns-3 is a discrete-event network simulator, with a particular emphasis on network research and education.

Users of ns-3 can construct simulations of computer networks using models of traffic generators, protocols such as TCP/IP, and devices and channels such as WiFi, and analyze or visualize the results. Simulation plays a vital role in the research and education process, because of the ability for simulations to obtain reproducible results (particularly for wireless protocol design), scale to large networks, and study systems that have not yet been implemented. A particular emphasis in ns-3 is the high degree of realism in the models (including frameworks for real application and kernel code) and integration of the tool with virtual machine environments and testbeds; we view that researchers need to move more effortlessly between simulation, testbeds, and live experiments, and ns-3 is designed to facilitate that.

Google Summer of Code organizational admins for ns-3 are [mailto:tpecorella@mac.com Tommaso Pecorella] and [mailto:tomh@tomh.org Tom Henderson]; contact them with any questions. They also hang out on [https://ns-3.zulipchat.com Zulip]. The project has participated in past GSoCs during 2008-10, 2012-15, and 2017-18.

Mentors will be paired with students based on the projects that are selected. Mentors from companies are welcome, if the employer will permit the mentor sufficient time to perform the mentoring. Prospective mentors should notify Tom Henderson or Tommaso Pecorella of interest. Mentors familiar with ns-3 development practices will be preferred, to improve the chances of student code merge. In 2019, we are going to be seeking two-person mentoring teams for projects, to help with the mentoring workload and bring more expertise.

=== Students: how to participate ===

For students interested in applying to ns-3 for GSOC, first wait to see if ns-3 will be selected. If so, then go through the following list to get started:
* Read the official [http://en.flossmanuals.net/GSoCStudentGuide/ GSoC student guide].
* Read [[GSOC2018StudentGuide |ns-3's GSoC Student guide]].
* Look through our [[#Project Ideas]] below to see if you find a project that interests you.
* Review the [http://www.nsnam.org/ns-3-29/documentation/ns-3 tutorial] thoroughly, if you have not already done so.
* Look through the [[GSOC2018StudentApplicationTemplate |GSoC Student application template]] to start preparing your proposal.
* Next, proceed to get in touch with the developers on the mailing list and refine your proposal.
* In parallel, make sure you prepare a patch as per the [[GSOC2018PatchRequirement | Patch Requirement Guidelines]] (to be revised). Your application to ns-3 will not be considered if you do not fulfill this requirement.

Below is a list of [[#Project Ideas]] proposed by the ns-3 team for Google Summer of Code 2019. Please note that these ideas are not limited to GSoC; anyone is welcome to work on them. Please email the [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers list] if you have a different idea that you'd like to work on, to see if a mentor may be interested. Applicants are encouraged to look over this list, pick one that especially interests them, think about it, and discuss potential approaches on the [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers list]. Previous experience with the Google Summer of Code programmes suggest that the more you discuss and refine your proposal on the mailing list beforehand, the stronger the proposal it will develop into, and the higher your chances of being accepted into the programme.

<blockquote>
Each project idea within a particular priority has been tagged with the following properties:
* ''Required Experience:'' Languages, concepts, or packages with which applicants must be familiar.
* ''Bonus Experience:'' Other experience or familiarity which would be greatly helpful to applicants for this project.
* ''Interests:'' Areas of particular relevance to this project, and an indicator of where successful students might apply their experiences coming out of this project.
* ''Difficulty:'' easy, medium or difficult
* ''Recommended reading:'' pointers to documentation, papers, specific bugs, etc.

Note that all of the projects require some experience and comfort with C++. Project ideas for which C++ is noted as a required experience will require more and deeper familiarity with the language. A similar notion applies to computer networking, BSD sockets, etc: Familiarity is strongly preferred, but is not required except where explicitly noted due to the topic being more advanced in that regard.
</blockquote>

=== Mentors: how to participate ===

The ns-3 project is open to the proposal of new project ideas by developers interested in being a GSoC mentor. For mentors who're adding project ideas to the list below, please ensure that:

* The projects are sized such that there can be a code merge by the end of the coding period. The scope of the project should be such that it is very difficult to not have a code merge by the end of the summer.
* The proposed projects are not too open-ended. That is, if the deliverables or a clear path to the same are not well understood, it is better kept outside GSOC.
* There should be a clear merge path to one of the main project code repositories (ns-3-dev, ns-3-dce, bake) by the end of the summer, either because the patches directly apply to these repositories, or because they apply to an ns-3 module that is in the process of being merged with ns-3-dev.

== Project Ideas ==

'''Note to students:''' These ideas are not listed in any priority order. The list of mentors for 2019 includes Mohit Tahiliani, Alexander Krotov, Abhijith Anilkumar, Ankit Deepak, Dizhi Zhou, and Gabriel Arrobo, and others are in discussion.

==== Usability improvements ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], Dizhi Zhou, others TBD

Usability of ns-3 can always be improved, whether it is help with building simulations, running simulation campaigns, using the ns-3 C++ API, improving the Python user experience, visualizing simulations or data, software packaging (e.g. binary packages or Docker containers), or documentation. This project is for a student who has been using ns-3 for a while and has ideas on how to make it better during GSoC. We don't want to limit the scope of proposals here; we will consider any project ideas that improve ns-3 usability in some way (please explain to us why the usability improvement is important to users beyond yourself, and why you would argue for your particular solution, and of course describe how you plan to get it done during the timeframe of GSoC). Some project examples:
* Tools and scripts to conduct and manage data from a large number of simulation runs
* How to integrate a more Python-centric data flow and tools, such as [http://jupyter.org/ Jupyter Notebook] and [https://github.com/bloomberg/bqplot bqplot]
* Internal state visualization of Wi-Fi or LTE, such as the kind of plots generated by [http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.126.3791&rep=rep1&type=pdf Yavista]

==== L4/L3 routing improvement ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

At the moment, each packet in ns-3 is routed independently. Even though this is a good behaviour for routers, it is not for the source node (expecially for TCP). As a matter of fact, when a TCP connection is established, *all* its packets should be directed to the very same output interface. The same goes for UDP when the source address is forced to be a specific one.
The project idea is to modify the TCP and UDP stacks so that they can store the source address after the connection phase, and skip part of the routing process.
* ''Required Experience:'' C++, TCP, UDP
* ''Bonus Experience:'' IPv4 and IPv6 routing
* ''Interests:'' TCP and UDP
* ''Difficulty:'' medium
* ''Recommended reading:''
** [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1041 Bug 1041]

==== NetDevice up/down consistency and event chain ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella], Manoj Kumar Rana

There in no actual consistency among the different modules about how to handle Up/Down events (e.g., when a link is lost).
This prevents some "normal" behaviours from happening, e.g., the DHCP IP address renegotiation, MIP implementation, etc.
As a matter offact, one should expect that an IP interface would be declared as "down" when its NetDevice is down... but it isn't. The goal of this project is to fix this behavior, to update some NetDevices so that they use Up/Down events consistently, to provide the documentation about what is the standard behavior, and what NetDevices are actually implementing it in the right way.
* ''Required Experience:'' C++, NetDevices, Interface behavior
* ''Bonus Experience:'' NetDevice and IP behavior
* ''Interests:'' NetDevice and IP behavior
* ''Difficulty:'' medium

==== Wi-Fi mesh module upgrade ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

ns-3 Wi-Fi mesh module was written about 8 years ago, and is not completely up to date with the standard, nor does it work with newer Wi-Fi variants (802.11n/ac/ax). This project would prioritize making mesh module compatible with all variants of Wi-Fi and would align with the latest standard. Going further, some scenarios and scripts that align ns-3 simulations with how community networks are set up and configured would be helpful, such as guidance on how to configure rate controls and routing protocols (e.g. how to run OLSR on top of mesh).

* ''Required Experience:''C++, Wi-Fi and mesh understanding
* ''Interests:'' mesh networking
* ''Difficulty:'' Medium
* ''Recommended reading:'' mesh issues in the [https://www.nsnam.org/bugzilla/buglist.cgi?component=mesh&product=ns-3&query_format=advanced&resolution=--- tracker], and the mesh module documentation, and IEEE 802.11 standard

==== Direct Code Execution upgrade ====

Mentor: [mailto:mattator@gmail.com Matthieu Coudron]

ns-3 has an extension known as Direct Code Execution, which allows users to build C or C++-based applications, and open source (Linux, FreeBSD) kernels, into ns-3. However, support for the latest kernels (e.g. Linux kernel 4 series) and latest gcc versions has languished. We also could better integrate DCE with the main ns-3 tree. This project seeks a student interested in DCE, improving usability, and making it current with latest kernels and toolchains. The payoff of this type of project is very high since DCE makes available a lot of real-world models for use in ns-3. If you select this project idea, please engage with us on the developers list, and consider to take a look at solving one of the [https://www.nsnam.org/bugzilla/buglist.cgi?bug_status=__open__&content=&no_redirect=1&order=Importance&product=dce&query_format=specific open DCE issues in our tracker], for starters.
* ''Required Experience:'' good hacking skills on Linux, C, C++, Python
* ''Difficulty:'' Hard.
* ''For more information:'' https://www.nsnam.org/overview/projects/direct-code-execution/dce-1-9/

==== Freshen ns-3/Click integration ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

ns-3 and [https://github.com/kohler/click Click modular routing] were first integrated in an [https://www.nsnam.org/wiki/GSOC2010Click ns-3 GSoC project] from 2010. We seek a student interested in the following tasks:

* Since 2010, Ipv4L3Protocol has continued to evolve, but Ipv4L3ClickProtocol has not kept pace with the changes. Also, IPv6 is not supported. Refactor Ipv4L3Protocol and Ipv4L3ClickProtocol (or delete Ipv4L3ClickProtocol altogether) so that the click-specific pieces are limited and can be maintained more easily.
** Current thoughts on this are that we would like to modify the approach. It would be nice for Click to run on ns-3 in a manner that is as close as possible to its working outside simulation (raw sockets + tun/tap devices). This will hopefully allow us to delete IPv4L3ClickProtocol and avoid needed ns-3 code to expect Click to provide a routing table. ns-3 traffic generators should then be able to send packets to an ns-3 equivalent of a tun/tap device (which doesn't presently exist), have packets show up in Click, and then get Click to push those packets directly to an interface using raw sockets from inside ns-3.
* There was an [https://www.nsnam.org/wiki/NSOC2011ClickMac/MidTermReport ns-3 2011 summer project] (not part of GSoC, but a follow-on project) to try to finish the integration with ClickMac. We'd like to update it, finish it off, and merge it with ns-3-dev. Some brief discussion was here: https://codereview.appspot.com/4890044/
** The blocking issue at the time was in the Wi-Fi module; the changes in radiotap and frame injection over monitor mode, which Click needed, were not finished (accepted).
* Anything else that a student thinks would be useful to support regarding click and ns-3 integration. Consider to review in the recent literature (see Google Scholar) how Click is now being used for research, and think about then what might be research-driven priorities for support in ns-3. Provide evidence (citations) in your application.

The list is not exhaustive and not limiting. I.e., the candidate can propose other points and/or concentrate on a specific subset.

* ''Required Experience:'' C++
* ''Bonus Experience:'' IPv4, IPv6, Click.
* ''Interests:'' Software integration.
* ''Difficulty:'' Medium.

==== User-friendly internet-apps ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

Ping is a ubiquitous application for reachability and latency measurements. ns-3 already has a ping model (the v4ping.cc and ping6.cc). However, a user-friendly API could still be added. It is not straightforward to configure an ns-3 program to do in a single statement, for example, "Ping the IP address W.X.Y.Z from node 0 between times 5 and 50 seconds in my program, and save the output in traditional format to the file <filename.txt>", or to configure the many options found in the ping man page. This project is therefore not about developing brand new features as much as it is about making ping super-easy to use with a great API. Have a look at how ns-3 programs are written, and tell us what kind of API makes sense to you, and why, and how you would go about prioritizing its implementation. If ping is solved very early, the project can follow the same pattern for one or two more applications (e.g. netperf, iperf, etc.).

* ''Required Experience:''C++
* ''Interests:'' Network performance management
* ''Difficulty:'' Medium
* ''Recommended reading:''

==== nam upgrade and support for ns-3 ====

Mentors: [mailto:tomh@tomh.org Tom Henderson]

[http://www.isi.edu/nsnam/nam/ nam] is a Tcl/Tk-based animator for ns-2. Some example videos are found at [https://www.youtube.com/results?search_query=nam+network+animator YouTube]. nam has been functionally replaced in many ways by [https://www.nsnam.org/wiki/NetAnim NetAnim], but it still has some attractive features and might make a complementary animation tool for ns-3. In fact, someone did a proof-of-concept support of nam for ns-3 many years ago: http://www.nsnam.org/contributed/ns-3-nam.tar.bz2. This project would involve upgrading nam support to the latest Tcl/Tk release series (8.6) and then using the existing ns-3 trace system to generate nam output files such as in ns-2, and documenting and testing the results, including some demonstration videos.

* ''Required Experience:''C++, Tcl/Tk also preferred
* ''Interests:'' Network visualization/animation
* ''Difficulty:'' Medium
* ''Recommended reading:''
** the links listed above

==== ns-2 ports to ns-3 ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani]

[http://www.isi.edu/nsnam/ns/ ns-2] is the predecessor to ns-3, but some popular models still exist in ns-2 and are not yet ported to ns-3. Google Scholar can be used to find topics for which people still are publishing papers using ns-2. This project idea is for someone who is fond of some feature or model found in ns-2 but not in ns-3. A successful application of this type will make a good case that the port is still relevant to network research, that people are using ns-2 due to this model, and will describe the technical approach that is planned to make the port (e.g. how OTcl default variables will be ported to ns-3). Please note that the networking relevance is very important part of the application; if you propose to port some feature of ns-2 that is dated or unlikely to be of much interest because its applicability is very narrow, your proposal will not be selected.

* ''Required Experience:''C++, ns-2 also preferred
* ''Difficulty:'' Low to medium
* ''Recommended reading:''
** ns-2 and ns-3 manuals

==== TCP testing and alignment ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani], [mailto:natale.patriciello@gmail.com Natale Patriciello]

ns-3 needs good TCP models that align with real implementations, or that have documented differences. In particular, does ns-3 TCP's slow start and congestion avoidace perform like a real implementation, including common variants found in the field (CUBIC, DCTCP), and ones under development (TCP Prague, BBR). The project should also produce regression tests. We envision that this project will consist of setting up ns-3 in emulation mode to test operation of its implementation against real implementations, in different impairment environments, documenting the results, and figuring out how to take the ns-3 results and generate regression tests.

* ''Required Experience:''C++, TCP
* ''Difficulty:'' Medium
* ''Recommended reading:''
** Similar FreeBSD test suite: https://wiki.freebsd.org/SummerOfCode2016/TCP-IP-RegressionTestSuite
** https://wiki.linuxfoundation.org/networking/tcp_testing

==== TCP analysis ====

Mentors: [mailto:tomh@tomh.org Tom Henderson], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani], [mailto:natale.patriciello@gmail.com Natale Patriciello]

This project is not about developing new TCP variants, but about developing a TCP analysis capability that is user-friendly and produces output similar to (perhaps integrates with?) tools such as [http://research.protocollabs.com/captcp/ captcp], [http://www.wireshark.org Wireshark TCP analysis], [http://www.tcptrace.org/ tcptrace], [http://tstat.polito.it/ Tstat], or other similar tools. An important part of your application will be a description of how a user will enable it in a user program, and some description of how it will be implemented.

As an example, consider providing the user with the ability to auto-generate plots of throughput evolution, congestion window evolution, etc. over time, for a pair of 4-tuples where the 4-tuples may contain wild cards or regular expressions. For instance, the user specifies "10.0.0.1:*" and "192.168.0.1:80", and if there are three connections in the simulation from 10.0.0.1 to that specific IP address and port, then three sets of time-series plots are generated and labelled appropriately.

* ''Required Experience:''C++, TCP
* ''Difficulty:'' Medium
* ''Recommended reading:''
** ns-2 and ns-3 manuals

==== 802.15.4 Bootstrap ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The lr-wpan model is an 802.15.4 PHY and MAC model currently in development. The model is able to simulate an 802.15.4 network in ad-hoc mode, much like Contiki-os nodes do. An useful extension is to fully support the node bootstrap phase, including node association and beacon request/reply. The goal of the project is to enhance the lr-wpan module so to use beacons in the bootstrap phase along with network scanning and pan-id resolution for in-range coordinators.
* ''Required Experience:'' C++, WSN
* ''Bonus Experience:'' 802.15.4 standard
* ''Interests:'' WSN
* ''Difficulty:'' medium
* ''Recommended reading:''
** [http://standards.ieee.org/getieee802/download/802.15.4-2011.pdf 802.15.4 Standard]

==== 802.15.4 Beacon-enabled mode ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The lr-wpan model is an 802.15.4 PHY and MAC model currently in development. The model is able to simulate an 802.15.4 network in ad-hoc mode, much like Contiki-os nodes do. Unlike Contiki-os, the model could benefit from supporting beacon-enabled mode of operation. The beacon-enabled mode is a fully slotted transmission mode, with guaranteed slots and bound performances, unlike the ad-hoc mode. This is especially important because the L3 routing protocols might be strongly affected by the lower-layer topology. Hence it is of paramount importance to be able to simulate both in ns-3. The goal of the project is to develop the new beacon-enabled MAC layer for the lr-wpan module.
* ''Required Experience:'' C++, WSN
* ''Bonus Experience:'' 802.15.4 standard
* ''Interests:'' WSN
* ''Difficulty:'' medium/hard
* ''Recommended reading:''
** [http://standards.ieee.org/getieee802/download/802.15.4-2011.pdf 802.15.4 Standard]

==== DSR routing RFC compliance ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

The DSR routing module is not compliant with the RFC 4728. This leads to a number of small issues, like simulation imprecision and impossibility to decode the messages with Wireshark.
The goal of the project is to enhance the current model and to make it RFC-compliant, eventually doing a code refectory where needed.
A possible enhancement over the base protocol could also be to include support for IPv6 in the implementation.
* ''Required Experience:'' C++
* ''Bonus Experience:'' DSR standard
* ''Interests:'' Ad-hoc routing
* ''Difficulty:'' medium
* ''Recommended reading:''
** [http://www6.ietf.org/rfc/rfc4728.txt RFC 4728]

==== Enable IPv6 support for Ad hoc Routing Protocols in ns-3 ====

Mentors: [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella], [mailto:tahiliani.nitk@gmail.com Mohit P. Tahiliani]

ns-3 contains models for proactive (DSDV and OLSR) and reactive (AODV and DSR) ad hoc routing protocols. However, these models are IPv4-only and do not provide support of IPv6 addressing. This project aims to enable IPv6 support for ad hoc routing protocols in ns-3, mainly for AODV and DSR. There are out-of-tree implementations of OLSR and DSDV that provide support for IPv6 addressing, and can be used as references to get started with this project.
An important point of the implementation should be code duplicate minimization, in order to have the minimize maintenance efforts.
Note: Enabling IPv6 support for these protocols is not a matter of simply changing out an IPv4-formatted address for an IPv6-formatted address. The IPv6 addressing architecture emphasizes scoping much more than does IPv4 (RFC 4007). Please suggest in your application how IPv6 address configuration (and possibly auto-configuration?) and address scopes (e.g. link-local vs. global) should be used in these protocols. Consulting the RFCs is highly recommended.'

* ''Required Experience:'' Fundamentals of IPv6 addressing, C++ programming.
* ''Bonus Experience:'' Familiarity with AODV and DSR implementations in ns-3
* ''Interests:'' Ad hoc routing
* ''Difficulty:'' Medium.
* ''Recommended reading:''
** [https://www.nsnam.org/docs/models/html/ipv6.html IPv6 model in ns-3]
** [https://www.nsnam.org/docs/models/html/aodv.html AODV model in ns-3]
** [https://www.nsnam.org/docs/models/html/dsr.html DSR model in ns-3]
** [https://www.nsnam.org/workshops/wns3-2016/posters/IPv6-support-for-OLSR.pdf IPv6 Support for OLSR in ns-3]

==== Data collection and statistics framework extension ====

Mentors: [mailto:dizhizhou@hotmail.com Dizhi Zhou]

The goal of this project is to extend and add more functionalities on ns-3 data collection and statistics framework (source code:ns-3.27/src/stats/) which was added in ns-3.18. The model was implemented based on the ns-3 tracing system. It has two major functions. 1) retrieve data from multiple ns-3 trace sources and then recalculate/transform the data into a user-defined format. However, not all the trace source types are supported. 2) use a data collector to calculate some useful statistics from a ns-3 trace source (e.g. max and min of the trace value). However, only supports counter and min/max data collectors are supported today. In order to make the model more useful, more trace source types, output formats and collectors need to be added.

A parallel project of ns-3, named sns3, proposed an enhancement on this model in 2016. But the patch was not merged to the official release yet. Student may use this patch as a reference for their proposals. Some sample ideas are listed below.
* ''Help to merge sns3 statistic enhancement to ns-3.
* ''Add more trace types
* ''Add more collectors. Ideally, the statistic calculation method should be configurable in the script so that people don’t need to add new collectors when they have any new requirement.
* ''More output format types: excel, MySql, matplotlib, R, Matlab, more picture formats, etc.
* ''Improve documentation and add more example scripts.

The list is not exhaustive and not limiting. Any new ideas in this area are welcome.
* ''Required Experience:'' C++ programming.
* ''Bonus Experience:'' Proficiency with open source data handling software (e.g. R, matplotlib, SQLite, gnuplot)
* ''Difficulty:'' Medium.
* ''Recommended reading:''
** [https://www.nsnam.org/documentation/ Data collection and trace chapters in ns-3 tutorial/manual/model library]
** [https://codereview.appspot.com/318800043/ Statistic model enhancement code review from sns3 project]

==== Persistent and Semi-Persistent Scheduling inside LTE module ====

Mentors: [mailto:natale.patriciello@gmail.com Natale Patriciello], [mailto:sandra.lagen@cttc.cat Sandra Lagen]

The goal of this project is to implement Semi-Persistent Scheduling (SPS) scheme in the ns-3 LTE module. SPS scheme is enabled in 4G LTE, as well as in 5G, in order to save L1/L2 (layer 1/layer 2) control signaling and reduce resource overhead for some periodic and predictable traffic, such as voice over IP (VoIP) and traffic from sensors/IoT devices. Currently, in ns-3 LTE, only Dynamic Scheduling (DS) scheme is implemented, for which the scheduling decisions are dynamically signaled on L1/L2 control to indicate the allocated resources. Differently, in SPS, only the first scheduling assignment is signaled on L1/L2, and the subsequent transmissions use the same resources with a preconfigured interval, thus reducing L1/L2 overhead. In particular, SPS periodicity is configured by RRC, and then activation is signaled through the downlink control information (DCI), both for downlink and uplink SPS. The idea of this project is to extend RRC parameters, and DCI formats, to enable SPS scheme, and to update the MAC scheduler (L2) to enable both SPS and DS schemes for different traffic simultaneously. The later requires, among others, a memory in the scheduler, so as not to allocate resources for DS that are already scheduled for SPS.

* ''Required Experience:'' C++, LTE understanding
* ''Bonus Experience:'' Familiarity with lte module
* ''Interests:'' LTE scheduling (MAC layer)
* ''Difficulty:'' Medium.

==== Structured logging support ====

Mentors: [mailto:krotov@iitp.ru Alexander Krotov], ?

Sometimes an experiment with a hard to find bug takes a lot of time to run, so it may be desirable to collect as much information is possible and process it later, without adding traces and running experiment again multiple times.

Existing NS-3 logging framework does not support structured logging. It is only capable of printing text messages, which are hard to process automatically. In fact, [https://www.nsnam.org/docs/manual/html/logging.html NS-3 manual] even contains a warning:
<blockquote>
The project makes no guarantee about whether logging output will remain the same over time. Users are cautioned against building simulation output frameworks on top of logging code, as the output and the way the output is enabled may change over time.
</blockquote>

Currently logs often lack context information, such as MAC addresses, node IDs etc. Even if the required information is present, extracting it from text messages is error-prone, and message format may change from version to version even when the required data is still available. As a result, it is often easier to resort to installing traces and adding conditionals to the NS-3 code, recompiling the code and re-running experiments.

Structured logging, sometimes called semantic logging, is an approach that solves the problem of logs not being machine-readable.

For example, instead of writing
<code>
NS_LOG_LOGIC ("Route to " << m_endPoint->GetPeerAddress () << " does not exist");
</code>
it will be possible to write something like
<code>
NS_LOG_LOGIC ("Route to {peer_address} does not exist",
"peer_address", m_endPoint->GetPeerAddress (),
"id", "route_not_exist");
</code>

When used in text mode, the logging framework will output messages as usual. In addition, it will be able to store messages as dictionaries, for example in [http://jsonlines.org/ JSON Lines], [http://cbor.io/ some binary format] or a [https://docs.mongodb.com/ecosystem/use-cases/storing-log-data/ database].

The message above could be represented as
<code>
{
"message": "Route to {peer_address} does not exist",
"peer_address": {"type": "ipv4", "192.168.1.1"},
"id": "route_not_exist"
...
}
</code>
In addition, messages need to contain some context, extracted from object <code>this</code>, object identifier (its pointer) and timestamp.

The goal of this project is to
* Add API to serialize NS-3 object to dictionaries.
* Implement structured logging framework in the <code>core</code> module.
* Implement at least text and JSON output, extensible to add more output formats later.
* Add structured logging support to at least some modules, e.g. <code>applications</code>. It should be possible to incrementally switch to structured logging support later.

There are hardly any C++ structured logging frameworks. There is a https://github.com/kevincox/sog, which is abandoned and uses Apache 2.0 license, that is incompatible to NS-3 license (GPLv2). As a result, it will probably be required to implement the whole framework from scratch. Structured logging frameworks for other languages, such as https://serilog.net/, can be used for inspiration.

* ''Required Experience:'' C++
* ''Difficulty:'' medium

[[Category:GSoC]]

Git Migration

2018-12-12T10:59:23Z

Krotov: /* Branch management and workflow */ Add simplified workflow description

= Git Migration =
This page recap all the open questions for the migration to the git tool for managing source code and their answers.

We all agree on the fact that a giant, important step like this requires coordination, and the feedback/contribution of many people as possible, especially current maintainers. The process of updating the source code management system will be split into different sequential phases. Each phase will be used as input for the next stage.

'''Phase 1 (done)''': ''Definition of questions to be answered: '' Each ns-3 users can put questions on this page that he/she would like to have it answered. The problems can have multiple points. Users can add points to each item.

'''Phase 2 (done)''': ''Live talks in wns3: '' In this week the proposal can be discussed live.

'''Phase 3 (done)''': ''Discussion of options: '' Each developer starts answering the questions (even not his/her own) with his/her proposal. Each proposal can be refined, discussed on the mailing list, and so on. Plan to do this at Google Hangout on October 10, 15:00 UTC (contact tomh@tomh.org if interested).

'''Phase 4 (done)''': ''list discussion: '' If there are questions with conflicting proposals, the current maintainers will have a vote on what plan should be implemented.

'''Phase 5''' ''- Implementation:'' The maintainers will start migrate the source code. At the end of the phase, the community will give comments. Discuss, integrate, iterate until final release.

= Phase 1 =

Each ns-3 user was free to add questions that he/she would like to have answered. The objective was to have a coherent set of stakeholder interests, as well as a set of design rules that take into considerations these interests. The reality is that we have a different way of working, and it is difficult to have something that is good enough for everyone. Below were the questions raised and conclusions later drawn.

# (nat) Should we move some modules to move to contrib? <- No; this can be done as a subsequent step
# (nat) What modules should we move to contrib? <- None
# (nat) Define how the contrib/ modules will be fetched and compiled <- Using bake or plain download
# (nat) Define the service we will use (GitHub, GitLab, BitBucket) <- GitLab
# (nat) Define the official branches (stable releases, development) <- See workflow discussion below
# (nat) Define how the versions are managed and released <- See workflow discussion below
# (nat) Define a workflow for integrating patches: <- See workflow discussion below
## (nat) stable fixes (fixes that are for an already shipped version)
## (nat) development fixes/features (fixes and features for master branch)
# (nat) Define the accepted code review models <- GitLab Merge Review, others (GitHub, code review) can still be used
# (nat) Define the permissions of each user inside the projects (should everyone have r/w access to the repo?) <- Use GitLab groups to manage access
# (rediet) Define how issues/bugs will be reported (e.g. special rights needed?) <- Will migrate to GitLab tracker
# (rediet) Will current features (currently managed through wiki) be handled by service (e.g. artefact)? <- Keep wiki and static server, start to use GitLab features (CI/CD, GitLab pages, tracker) over time.

= Phases 2, 3, 4 =

Historic details omitted herein but after discussion throughout the summer, including list discussion and offlist maintainer discussions, and testing of three popular cloud-hosted services (GitHub, GitLab, Bitbucket), decision was taken to use GitLab cloud (GitLab.com) as hosting service.

= Phase 5 =

We plan to migrate to GitLab.com by year's end. Below is a proposed strawman of things to be done. Natale has volunteered to implement the main things.

== Repository layout ==

The main tree will be at https://gitlab.com/nsnam/ns-3-dev.git

Bake will have a tree at https://gitlab.com/nsnam/bake.git

Static web site (jekyll) will be at https://gitlab.com/nsnam/nsnam-www.git

'''Open issue:''' should we continue to use ns-3-allinone or transition to bake? If we continue to use ns-3-allinone, suggest to put a repository at https://gitlab.com/nsnam/ns-3-allinone.git

* Suggested resolution to issue: Migrate also the 'ns-3-allinone' repository; it may continue to be used for holding scripts like dist.py for building source release tarballs, regardless of whether we continue with build.py.

== Subgroups ==

No subgroups initially; subgroups may be created in the future for documentation not already maintained with ns-3-dev (e.g. tutorial translations, install guides), or for ns-3 modules for the app store.

== Branch management and workflow ==

Peter has suggested to consider the gitflow workflow (https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). This would seem to align with our release practices (so long as we introduce also the 'support' branches described in this StackOverflow issue: https://stackoverflow.com/questions/16386323/following-git-flow-how-should-you-handle-a-hotfix-of-an-earlier-release

Currently a simplified workflow, roughly resembling our Mercurial workflow, is adopted:

* Commit obvious non-critical fixes (documentation improvements, typos etc.) directly into the master branch.

* For each new major feature, create a feature branch in your own fork

* Merge feature branches into master after review.

* Tag releases wherever they are, either on the master or support/release branch. Tags are visible globally in git, they are not commited to special .hgtags like in Mercurial.

* If minor releases are required, create support branch for the major release and push fixes there. Tag minor releases accordingly.

* If hotfix needs a review, start a "hotfix" branch and create MR.

* Merge support branch back into master if hotfix is relevant.

== Code reviews ==

The primary review mechanism will be for contributors to create a GitLab Merge Request by forking ns-3-dev and using GitLab tools to generate and update merge requests. At the end of this process, maintainers will work with the submitter to create either a squash merge or full merge as appropriate.

Small patches (a few lines) could still be handled with raw diff/patch files in the tracker.

'''Open issue:''' Do we allow pull requests on GitHub and Bitbucket, and use tools there (if the maintainer agrees to perform reviews there) or do we request that they all come to GitHub merge requests? To date, we have not encouraged these, but many GitHub users may find it easier to submit. Perhaps there is an easy workflow for maintainers to rebuild GitHub pull requests on GitLab as merge requests.

* Suggested resolution to issue: Do not have duplicate issues on GitHub and GitLab. Try to migrate issues to GitLab. GitHub and Bitbucket can stay as mirror. Consider to expire PRs after some time (3 months?), after which the submitter must resubmit.

'''Open issue:''' Do we allow people to continue to use codereview.appspot.com for some large reviews? We have some active reviews there and it may be useful to have as a backup service also.

* Suggested resolution to issue: Allow codereview.appspot.com reviews for the time being, until if and when we are comfortable that the Merge Review process can replace it. Do not duplicate (mirror) Merge Review and codereview issues, to avoid confusion about where to review.

== Continuous Integration ==

Need volunteer to experiment with daily builds on GitLab.com CI infrastructure, and to propose a workflow allowing for CI testing before final commit. This step is not needed to make the cutover (can still rely on existing Jenkins).

== Issue Tracker ==

New issues will go to the ns-3-dev tracker on GitLab.com. This needs to be configured with email hook to ns-bugs@isi.edu.

Previous issues will stay on ns-3 Bugzilla for now; may export and import to GitLab at a future date.

== Documentation ==

Tutorial must be updated (Getting Started section).

New documentation for end-user best practices for using GitLab.com with ns-3 should be written.
# How to fork and generate a merge request (walk through the lifecycle including iterations on a code review)
# Recommended branch management (when to (not to) squash, rebase, create a new branch, delete a branch, etc.)
# How to submit an issue to the issue tracker

New documentation for maintainers best practices using git and GitLab.com should be written.
# When to squash merge or not
# How to test a proposed Merge Request
# How to handle code that comes from other sources (GitHub, bugzilla, codereview)
# what not to do (e.g. rebase on public branches)

== code.nsnam.org status ==

This Mercurial service will remain open, but pushes to bake and ns-3-dev will be disabled.

GSOC2017Lte

2017-08-28T22:04:12Z

Krotov: /* Fixed bugs */

{{TOC}}

Return to [[GSOC2017AcceptedProjects | GSoC 2017 Accepted Projects]] page.

= Project overview =

* '''Project name:''' Enabling LTE CA handover to secondary cell

* '''Student:''' [mailto:ilabdsf@gmail.com Alexander Krotov]

* '''Mentor:''' [mailto:biljana.bojovic@gmail.com Biljana Bojovic]

* '''Abstract:''' The goal of the project is to implement handover to secondary cell, i.e. implement the ability to switch primary cell and reconfigure secondary carriers over RRC in runtime.

* '''Code:''' https://bitbucket.org/labdsf/ns-3-dev

* '''About me:''' PhD student at [https://mipt.ru/en/ Moscow Institute of Physics and Technology].

= Technical Approach =

In current LTE carrier aggregation (CA) model of ns-3 the handover among different component carriers is not supported. This is because the current LTE CA model does not treat different component carriers as different cells. Additionally, the primary component carrier is fixed and there is no procedure that allows change of a primary component carrier. In order to allow handover among component carriers, it is necessary to enhance SAP interfaces between RRC and component carrier manager (CCM), and also between CCM and lower layers (MAC, PHY) to allow change of primary component carrier, and also to extend the model so that each component carrier is treated as independent cell.

Currently cells have several identifiers. Firstly, according to LTE specifications, each cell has its own Cell ID. UE can learn this ID by communicating with eNB, so it always corresponds to Cell ID on eNB.
Secondly, for the needs of scheduler, which is implemented according to LTE Femtocell Scheduler API, each cell is identified internally within eNB by its 8-bit identifier (componentCarrierId).

On the one hand, UE is unnecessarily aware of eNB configuration. componentCarrierIds are configured by LteHelper, so PHYs on eNB and UE correspond one-to-one. However, they don't have to, and it may be convenient to reserve componentCarrierId = 0 for primary CC on each UE. It is even possible that number of PHYs on eNB and UE is not equal.
On the other hand, entities such as LteEnbNetDevice have "CellId" attributes, which correspond to "primary" component carrier. As "primary" component carrier is a property of UE, not eNB, it is necessary to remove such attributes.

As distinction between primary and secondary carrier is done on each UE, any flags that identify primary carrier should be removed from eNB and scenario configuration.
For example, ComponentCarrier class has "PrimaryCarrier" boolean attribute which should be removed.

General plan is as follows:
# Improve architecture of LTE CA to make sure secondary cells are treated the same way as primary cells by eNB and frequency channels can be switched easily on UE.
# Implement minimally feasible version of handover procedure on eNB and UE and write unit tests for this procedure.
# Implement necessary signalling on RRC to make handover negotiation possible.
# Implement handover algorithm to make automatic handover possible.
# Write a scenario to validate implemented functionality and provide an example of usage for implemented functionality.

= Milestones and Deliverables =

== Phase 1 (May 30, 2017 - June 30, 2017) ==

In Phase 1 I made UEs receive secondary cell configuration over the wireless channel during initial cell selection instead of requiring them to be preconfigured and made it possible to use any of the component carriers as primary, including scenarios where different UEs have different primary component carriers.

# Made LteHelper create one SpectrumChannel for all carrier frequencies to allow PHYs to switch frequency without need to change the channel object.
# Assigned different physical cell IDs to different component carriers of the same eNB.
# Extended UeManager to track which cell ID is the primary component carrier for attached UE instead of assuming that primary cell is always on some fixed frequency.
# Fixed serialization of RRC messages carrying secondary component carrier configuration and modified UE RRC to read it during initial connection configuration.
# Made eNB transmit SIB1 (SystemInformationBlockType1) and SIB2 messages on all frequencies.
# Implemented test suite <code>lte-test-secondary-cell-selection.cc</code> to test that UE can attach to any component carrier (not just the 0-th one) during initial cell selection. Run it with <code>./test.py -s lte-secondary-cell-selection</code>
# Implemented test suite <code>lte-test-aggregation-throughput-scale.cc</code> to test that throughput scales linearly with number of CCs. It proves that initial configuration is correct in both downlink and uplink channels as UE transmits CQI (channel quality indicator) in uplink and eNB transmits data to UE in downlink using high MCS. Run it with <code>./test.py -s lte-aggregation-throughput-scale</code>

Report and code review:
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013983.html Phase 1 mailing list report]
* [https://codereview.appspot.com/327850043 Phase 1 code review]

Code is already merged upstream:

* [https://code.nsnam.org/index.cgi/ns-3-dev/rev/bb02103e2b8d Official repository]
* [https://github.com/nsnam/ns-3-dev-git/commit/6837edc5a961d0f1ba9332d4293934af87273e5d GitHub mirror]

== Phase 2 (June 30, 2017 - July 24, 2017) ==

In phase 2 I made it possible to trigger UE handover with and without enabled CA (carrier aggregation) in inter-eNB, intra-eNB, inter-frequency and intra-frequency scenarios. Previously only inter-eNB intra-frequency handover was supported and only in non-CA scenarios.

# Modified EPC code to make it possible to identify eNB by any of its cell IDs instead of the first one.
# Made sure LteEnbRrcProtocolIdeal is able to deliver messages regardless of which CellId is used.
# Extended API to make it possible to specify target component carrier for handover.
# Extended existing test suite <code>test-lte-handover-delay.cc</code> to make it possible to change the number of CCs. This test implements inter-eNB intra-frequency handover scenario and checks that delay is within limits. Run it with <code>./test.py -s lte-handover-delay</code>
# Implemented a test suite <code>lte-test-primary-cell-change.cc</code> to extensively test all mentioned above handover cases (inter/intra-eNB, inter/intra-frequency, various number of CCs). Run it with <code>./test.py -s lte-primary-cell-change</code>

Report and code review:
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014047.html Phase 2 mailing list report]
* [https://codereview.appspot.com/328170043/ Phase 2 and 3 code review]

Code passed review and is ready for merge.

== Phase 3 (July 28, 2017 - August 21, 2017) ==

# Updated MeasResults serialization according to 3GPP TS 36.331
# Created one measurement object for each CC to allow setting up measurement reports for SCells
# Made it possible to setup A1 and A2 events for cells other than PCell
# Extended existing A3 and A2/A4 algorithms to setup multiple MeasurementIds for each component carrier
# Implemented a test suite <code>lte-test-secondary-cell-handover.cc</code> to test that A3 algorithm can perform inter-frequency handover based on A3 event measurements. Run it with <code>./test.py -s lte-secondary-cell-handover</code>

* [https://codereview.appspot.com/328170043/ Phase 2 and 3 code review]

= Project summary =

In this section I briefly describe what I have done according to [https://developers.google.com/open-source/gsoc/help/work-product Work Product Submission Guidelines].

In the project I have implemented handover to secondary cell in NS-3 LTE model with enabled carrier aggregation. Implementation of this functionality allows developing and evaluating handover algorithms in multi-carrier scenarios.

The original implementation was mostly based on LTE Release 9 and supported only static carrier aggregation configuration, so all UEs had to use the same frequency for primary cell. I extended the model with LTE Release 10..12 improvements to support UE-specific configuration and dynamic reconfiguration. I improved the model to treat each component carrier as an independent cell able to support UEs configured to use it as their primary component carrier. To support dynamic reconfiguration I implemented previously unsupported intra-eNB inter-frequency handover and extended event-based measurement framework (A1, A2, A3, A4 events) to make it possible to use existing and implement new handover algorithms which make decisions based on secondary cell channel conditions besides already supported primary carrier measurements. All added functionality is tested by either implementing new test suites or extending existing ones.

The project was divided into three milestones:

# Make UE (User Equipment) receive configuration via RRC (Radio Resource Control) protocol and test the ability of UE to attach to any component carrier of eNB (Enhanced Node B) and receive configuration in runtime.
# Make it possible to trigger manual handover in inter/intra-eNB and inter/intra-frequency cases. Test that handover is successfully performed.
# Make it possible to collect measurements from secondary cells and perform automatic handover to secondary cell based on received measurements.

All patches are available in the form of Rietveld code reviews:

* [https://codereview.appspot.com/328170043/ Phase 1]
* [https://codereview.appspot.com/328170043/ Phase 2 and 3 code review]

Most recent version of the code ready for merge is available at [https://bitbucket.org/labdsf/ns-3-dev/commits/branch/default Bitbucket]. The easiest way to obtain the code is to clone Mercurial repository from Bitbucket.

At this point all the planned milestones are reached. First milestone code is already merged upstream, second passed review and third is prepared for merge and submitted for review.

== Statistics ==

Phase 1 statistics

$ hg diff -c bb02103e2b8d | diffstat
...
28 files changed, 1136 insertions(+), 383 deletions(-)

Phase 2 and Phase 3 merge statistics:

$ hg diff -r 969140f099bb -r 413811934b31 | diffstat
...
53 files changed, 1537 insertions(+), 818 deletions(-)

== Fixed bugs ==

Some of the bugs encountered and fixed during GSoC are:

* [https://bitbucket.org/labdsf/ns-3-dev/commits/a512e8874ff5213e538984b44ce92d2423d4480a?at=default Made sure 300kHz spacing between CC is maintained as required by the standard.] See http://www.3gpp.org/technologies/keywords-acronyms/101-carrier-aggregation-explained for explanation on why it is necessary.
* [https://bitbucket.org/labdsf/ns-3-dev/commits/1b97a9ad84e7933f012d479482af0a441d975973?at=default Detached PHY from the channel on reset to avoid crashes when some signal is in-flight during reset]
* [https://bitbucket.org/labdsf/ns-3-dev/commits/bf596dc4887a030e144b083eedf4571a341baff6?at=default Removed unused variable]
* [https://bitbucket.org/labdsf/ns-3-dev/commits/610318f10ae8fbafbd40035a0789953d028dd562?at=default Reset received signals on PHY reset to avoid SINR calculations with signals received from different channels]
* [https://bitbucket.org/labdsf/ns-3-dev/commits/86b92b2c3a905ed724ddf42daee93700a4e1ef7b?at=default Fixed various RRC serialization bugs], opened [https://www.nsnam.org/bugzilla/show_bug.cgi?id=2754 bugzilla issue] for remaining bugs.

== Future work ==

Although all the planned work is done, here is a list of things that I plan to do after GSoC:

* Resolve any comments that may arise during code review and merge phase 2 and phase 3 code upstream.
* Fix a [https://www.nsnam.org/bugzilla/show_bug.cgi?id=2754 noncritical bug] I discovered in RRC message serialization during project implementation.
* Implement A6 event measurements. A6 event is triggered when some neighbor cell becomes better than secondary cell. A6 event configuration is transmitted in ASN.1 extension and [https://code.nsnam.org/index.cgi/ns-3-dev/file/a39655894155/src/lte/model/lte-asn1-header.cc#l309 serialization of extensions is not supported by NS-3 ASN.1 code yet], so it is impossible to implement right now and requires ASN.1 serialization API changes.

GSOC2017Lte

2017-08-28T22:02:31Z

Krotov: Updated final report

{{TOC}}

Return to [[GSOC2017AcceptedProjects | GSoC 2017 Accepted Projects]] page.

= Project overview =

* '''Project name:''' Enabling LTE CA handover to secondary cell

* '''Student:''' [mailto:ilabdsf@gmail.com Alexander Krotov]

* '''Mentor:''' [mailto:biljana.bojovic@gmail.com Biljana Bojovic]

* '''Abstract:''' The goal of the project is to implement handover to secondary cell, i.e. implement the ability to switch primary cell and reconfigure secondary carriers over RRC in runtime.

* '''Code:''' https://bitbucket.org/labdsf/ns-3-dev

* '''About me:''' PhD student at [https://mipt.ru/en/ Moscow Institute of Physics and Technology].

= Technical Approach =

In current LTE carrier aggregation (CA) model of ns-3 the handover among different component carriers is not supported. This is because the current LTE CA model does not treat different component carriers as different cells. Additionally, the primary component carrier is fixed and there is no procedure that allows change of a primary component carrier. In order to allow handover among component carriers, it is necessary to enhance SAP interfaces between RRC and component carrier manager (CCM), and also between CCM and lower layers (MAC, PHY) to allow change of primary component carrier, and also to extend the model so that each component carrier is treated as independent cell.

Currently cells have several identifiers. Firstly, according to LTE specifications, each cell has its own Cell ID. UE can learn this ID by communicating with eNB, so it always corresponds to Cell ID on eNB.
Secondly, for the needs of scheduler, which is implemented according to LTE Femtocell Scheduler API, each cell is identified internally within eNB by its 8-bit identifier (componentCarrierId).

On the one hand, UE is unnecessarily aware of eNB configuration. componentCarrierIds are configured by LteHelper, so PHYs on eNB and UE correspond one-to-one. However, they don't have to, and it may be convenient to reserve componentCarrierId = 0 for primary CC on each UE. It is even possible that number of PHYs on eNB and UE is not equal.
On the other hand, entities such as LteEnbNetDevice have "CellId" attributes, which correspond to "primary" component carrier. As "primary" component carrier is a property of UE, not eNB, it is necessary to remove such attributes.

As distinction between primary and secondary carrier is done on each UE, any flags that identify primary carrier should be removed from eNB and scenario configuration.
For example, ComponentCarrier class has "PrimaryCarrier" boolean attribute which should be removed.

General plan is as follows:
# Improve architecture of LTE CA to make sure secondary cells are treated the same way as primary cells by eNB and frequency channels can be switched easily on UE.
# Implement minimally feasible version of handover procedure on eNB and UE and write unit tests for this procedure.
# Implement necessary signalling on RRC to make handover negotiation possible.
# Implement handover algorithm to make automatic handover possible.
# Write a scenario to validate implemented functionality and provide an example of usage for implemented functionality.

= Milestones and Deliverables =

== Phase 1 (May 30, 2017 - June 30, 2017) ==

In Phase 1 I made UEs receive secondary cell configuration over the wireless channel during initial cell selection instead of requiring them to be preconfigured and made it possible to use any of the component carriers as primary, including scenarios where different UEs have different primary component carriers.

# Made LteHelper create one SpectrumChannel for all carrier frequencies to allow PHYs to switch frequency without need to change the channel object.
# Assigned different physical cell IDs to different component carriers of the same eNB.
# Extended UeManager to track which cell ID is the primary component carrier for attached UE instead of assuming that primary cell is always on some fixed frequency.
# Fixed serialization of RRC messages carrying secondary component carrier configuration and modified UE RRC to read it during initial connection configuration.
# Made eNB transmit SIB1 (SystemInformationBlockType1) and SIB2 messages on all frequencies.
# Implemented test suite <code>lte-test-secondary-cell-selection.cc</code> to test that UE can attach to any component carrier (not just the 0-th one) during initial cell selection. Run it with <code>./test.py -s lte-secondary-cell-selection</code>
# Implemented test suite <code>lte-test-aggregation-throughput-scale.cc</code> to test that throughput scales linearly with number of CCs. It proves that initial configuration is correct in both downlink and uplink channels as UE transmits CQI (channel quality indicator) in uplink and eNB transmits data to UE in downlink using high MCS. Run it with <code>./test.py -s lte-aggregation-throughput-scale</code>

Report and code review:
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013983.html Phase 1 mailing list report]
* [https://codereview.appspot.com/327850043 Phase 1 code review]

Code is already merged upstream:

* [https://code.nsnam.org/index.cgi/ns-3-dev/rev/bb02103e2b8d Official repository]
* [https://github.com/nsnam/ns-3-dev-git/commit/6837edc5a961d0f1ba9332d4293934af87273e5d GitHub mirror]

== Phase 2 (June 30, 2017 - July 24, 2017) ==

In phase 2 I made it possible to trigger UE handover with and without enabled CA (carrier aggregation) in inter-eNB, intra-eNB, inter-frequency and intra-frequency scenarios. Previously only inter-eNB intra-frequency handover was supported and only in non-CA scenarios.

# Modified EPC code to make it possible to identify eNB by any of its cell IDs instead of the first one.
# Made sure LteEnbRrcProtocolIdeal is able to deliver messages regardless of which CellId is used.
# Extended API to make it possible to specify target component carrier for handover.
# Extended existing test suite <code>test-lte-handover-delay.cc</code> to make it possible to change the number of CCs. This test implements inter-eNB intra-frequency handover scenario and checks that delay is within limits. Run it with <code>./test.py -s lte-handover-delay</code>
# Implemented a test suite <code>lte-test-primary-cell-change.cc</code> to extensively test all mentioned above handover cases (inter/intra-eNB, inter/intra-frequency, various number of CCs). Run it with <code>./test.py -s lte-primary-cell-change</code>

Report and code review:
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014047.html Phase 2 mailing list report]
* [https://codereview.appspot.com/328170043/ Phase 2 and 3 code review]

Code passed review and is ready for merge.

== Phase 3 (July 28, 2017 - August 21, 2017) ==

# Updated MeasResults serialization according to 3GPP TS 36.331
# Created one measurement object for each CC to allow setting up measurement reports for SCells
# Made it possible to setup A1 and A2 events for cells other than PCell
# Extended existing A3 and A2/A4 algorithms to setup multiple MeasurementIds for each component carrier
# Implemented a test suite <code>lte-test-secondary-cell-handover.cc</code> to test that A3 algorithm can perform inter-frequency handover based on A3 event measurements. Run it with <code>./test.py -s lte-secondary-cell-handover</code>

* [https://codereview.appspot.com/328170043/ Phase 2 and 3 code review]

= Project summary =

In this section I briefly describe what I have done according to [https://developers.google.com/open-source/gsoc/help/work-product Work Product Submission Guidelines].

In the project I have implemented handover to secondary cell in NS-3 LTE model with enabled carrier aggregation. Implementation of this functionality allows developing and evaluating handover algorithms in multi-carrier scenarios.

The original implementation was mostly based on LTE Release 9 and supported only static carrier aggregation configuration, so all UEs had to use the same frequency for primary cell. I extended the model with LTE Release 10..12 improvements to support UE-specific configuration and dynamic reconfiguration. I improved the model to treat each component carrier as an independent cell able to support UEs configured to use it as their primary component carrier. To support dynamic reconfiguration I implemented previously unsupported intra-eNB inter-frequency handover and extended event-based measurement framework (A1, A2, A3, A4 events) to make it possible to use existing and implement new handover algorithms which make decisions based on secondary cell channel conditions besides already supported primary carrier measurements. All added functionality is tested by either implementing new test suites or extending existing ones.

The project was divided into three milestones:

# Make UE (User Equipment) receive configuration via RRC (Radio Resource Control) protocol and test the ability of UE to attach to any component carrier of eNB (Enhanced Node B) and receive configuration in runtime.
# Make it possible to trigger manual handover in inter/intra-eNB and inter/intra-frequency cases. Test that handover is successfully performed.
# Make it possible to collect measurements from secondary cells and perform automatic handover to secondary cell based on received measurements.

All patches are available in the form of Rietveld code reviews:

* [https://codereview.appspot.com/328170043/ Phase 1]
* [https://codereview.appspot.com/328170043/ Phase 2 and 3 code review]

Most recent version of the code ready for merge is available at [https://bitbucket.org/labdsf/ns-3-dev/commits/branch/default Bitbucket]. The easiest way to obtain the code is to clone Mercurial repository from Bitbucket.

At this point all the planned milestones are reached. First milestone code is already merged upstream, second passed review and third is prepared for merge and submitted for review.

== Statistics ==

Phase 1 statistics

$ hg diff -c bb02103e2b8d | diffstat
...
28 files changed, 1136 insertions(+), 383 deletions(-)

Phase 2 and Phase 3 merge statistics:

$ hg diff -r 969140f099bb -r 413811934b31 | diffstat
...
53 files changed, 1537 insertions(+), 818 deletions(-)

== Fixed bugs ==

* [https://bitbucket.org/labdsf/ns-3-dev/commits/a512e8874ff5213e538984b44ce92d2423d4480a?at=default Made sure 300kHz spacing between CC is maintained.] See http://www.3gpp.org/technologies/keywords-acronyms/101-carrier-aggregation-explained for explanation.
* [https://bitbucket.org/labdsf/ns-3-dev/commits/1b97a9ad84e7933f012d479482af0a441d975973?at=default Detached PHY from the channel on reset to avoid crashes when some signal is in-flight during reset]
* [https://bitbucket.org/labdsf/ns-3-dev/commits/bf596dc4887a030e144b083eedf4571a341baff6?at=default Removed unused variable]
* [https://bitbucket.org/labdsf/ns-3-dev/commits/610318f10ae8fbafbd40035a0789953d028dd562?at=default Reset received signals on PHY reset to avoid SINR calculations with signals received from different channels]
* [https://bitbucket.org/labdsf/ns-3-dev/commits/86b92b2c3a905ed724ddf42daee93700a4e1ef7b?at=default Fixed various RRC serialization bugs], opened [https://www.nsnam.org/bugzilla/show_bug.cgi?id=2754 bugzilla issue] for remaining bugs.

== Future work ==

Although all the planned work is done, here is a list of things that I plan to do after GSoC:

* Resolve any comments that may arise during code review and merge phase 2 and phase 3 code upstream.
* Fix a [https://www.nsnam.org/bugzilla/show_bug.cgi?id=2754 noncritical bug] I discovered in RRC message serialization during project implementation.
* Implement A6 event measurements. A6 event is triggered when some neighbor cell becomes better than secondary cell. A6 event configuration is transmitted in ASN.1 extension and [https://code.nsnam.org/index.cgi/ns-3-dev/file/a39655894155/src/lte/model/lte-asn1-header.cc#l309 serialization of extensions is not supported by NS-3 ASN.1 code yet], so it is impossible to implement right now and requires ASN.1 serialization API changes.

GSOC2017Lte

2017-08-28T01:54:15Z

Krotov: GSoC report ready for submissions

{{TOC}}

Return to [[GSOC2017AcceptedProjects | GSoC 2017 Accepted Projects]] page.

= Project overview =

* '''Project name:''' Enabling LTE CA handover to secondary cell

* '''Student:''' [mailto:ilabdsf@gmail.com Alexander Krotov]

* '''Mentor:''' [mailto:biljana.bojovic@gmail.com Biljana Bojovic]

* '''Abstract:''' The goal of the project is to implement handover to secondary cell, i.e. implement the ability to switch primary cell and reconfigure secondary carriers over RRC in runtime.

* '''Code:''' https://bitbucket.org/labdsf/ns-3-dev

* '''Documentation:''' https://bitbucket.org/labdsf/ns-3-dev

* '''About me:''' PhD student at [https://mipt.ru/en/ Moscow Institute of Physics and Technology].

= Technical Approach =

In current LTE carrier aggregation (CA) model of ns-3 the handover among different component carriers is not supported. This is because the current LTE CA model does not treat different component carriers as different cells. Additionally, the primary component carrier is fixed and there is no procedure that allows change of a primary component carrier. In order to allow handover among component carriers, it is necessary to enhance SAP interfaces between RRC and component carrier manager (CCM), and also between CCM and lower layers (MAC, PHY) to allow change of primary component carrier, and also to extend the model so that each component carrier is treated as independent cell.

Currently cells have several identifiers. Firstly, according to LTE specifications, each cell has its own Cell ID. UE can learn this ID by communicating with eNB, so it always corresponds to Cell ID on eNB.
Secondly, for the needs of scheduler, which is implemented according to LTE Femtocell Scheduler API, each cell is identified internally within eNB by its 8-bit identifier (componentCarrierId).

On the one hand, UE is unnecessarily aware of eNB configuration. componentCarrierIds are configured by LteHelper, so PHYs on eNB and UE correspond one-to-one. However, they don't have to, and it may be convenient to reserve componentCarrierId = 0 for primary CC on each UE. It is even possible that number of PHYs on eNB and UE is not equal.
On the other hand, entities such as LteEnbNetDevice have "CellId" attributes, which correspond to "primary" component carrier. As "primary" component carrier is a property of UE, not eNB, it is necessary to remove such attributes.

As distinction between primary and secondary carrier is done on each UE, any flags that identify primary carrier should be removed from eNB and scenario configuration.
For example, ComponentCarrier class has "PrimaryCarrier" boolean attribute which should be removed.

General plan is as follows:
# Improve architecture of LTE CA to make sure secondary cells are treated the same way as primary cells by eNB and frequency channels can be switched easily on UE.
# Implement minimally feasible version of handover procedure on eNB and UE and write unit tests for this procedure.
# Implement necessary signalling on RRC to make handover negotiation possible.
# Implement handover algorithm to make automatic handover possible.
# Write a scenario to validate implemented functionality and provide an example of usage for implemented functionality.

= Milestones and Deliverables =

== Phase 1 (May 30, 2017 - June 30, 2017) ==

In Phase 1 I made UEs receive secondary cell configuration over the wireless channel during initial cell selection instead of requiring them to be preconfigured and made it possible to use any of the component carriers as primary, including scenarios where different UEs have different primary component carriers.

# Made LteHelper create one SpectrumChannel for all carrier frequencies to allow PHYs to switch frequency without need to change the channel object.
# Assigned different physical cell IDs to different component carriers of the same eNB.
# Extended UeManager to track which cell ID is the primary component carrier for attached UE instead of assuming that primary cell is always on some fixed frequency.
# Fixed serialization of RRC messages carrying secondary component carrier configuration and modified UE RRC to read it during initial connection configuration.
# Made eNB transmit SIB1 (SystemInformationBlockType1) and SIB2 messages on all frequencies.
# Implemented test suite <code>lte-test-secondary-cell-selection.cc</code> to test that UE can attach to any component carrier (not just the 0-th one) during initial cell selection. Run it with <code>./test.py -s lte-secondary-cell-selection</code>
# Implemented test suite <code>lte-test-aggregation-throughput-scale.cc</code> to test that throughput scales linearly with number of CCs. It proves that initial configuration is correct in both downlink and uplink channels as UE transmits CQI (channel quality indicator) in uplink and eNB transmits data to UE in downlink using high MCS. Run it with <code>./test.py -s lte-aggregation-throughput-scale</code>

Report and code review:
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013983.html Phase 1 mailing list report]
* [https://codereview.appspot.com/327850043 Phase 1 code review]

Code is already merged upstream:

* [https://code.nsnam.org/index.cgi/ns-3-dev/rev/bb02103e2b8d Official repository]
* [https://github.com/nsnam/ns-3-dev-git/commit/6837edc5a961d0f1ba9332d4293934af87273e5d GitHub mirror]

== Phase 2 (June 30, 2017 - July 24, 2017) ==

In phase 2 I made it possible to trigger UE handover with and without enabled CA (carrier aggregation) in inter-eNB, intra-eNB, inter-frequency and intra-frequency scenarios. Previously only inter-eNB intra-frequency handover was supported and only in non-CA scenarios.

# Modified EPC code to make it possible to identify eNB by any of its cell IDs instead of the first one.
# Made sure LteEnbRrcProtocolIdeal is able to deliver messages regardless of which CellId is used.
# Extended API to make it possible to specify target component carrier for handover.
# Extended existing test suite <code>test-lte-handover-delay.cc</code> to make it possible to change the number of CCs. This test implements inter-eNB intra-frequency handover scenario and checks that delay is within limits. Run it with <code>./test.py -s lte-handover-delay</code>
# Implemented a test suite <code>lte-test-primary-cell-change.cc</code> to extensively test all mentioned above handover cases (inter/intra-eNB, inter/intra-frequency, various number of CCs). Run it with <code>./test.py -s lte-primary-cell-change</code>

Report and code review:
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014047.html Phase 2 mailing list report]
* [https://codereview.appspot.com/328170043/ Phase 2 and 3 code review]

Code passed review and is ready for merge.

== Phase 3 (July 28, 2017 - August 21, 2017) ==

# Updated MeasResults serialization according to 3GPP TS 36.331
# Created one measurement object for each CC to allow setting up measurement reports for SCells
# Made it possible to setup A1 and A2 events for cells other than PCell
# Extended existing A3 and A2/A4 algorithms to setup multiple MeasurementIds for each component carrier
# Implemented a test suite <code>lte-test-secondary-cell-handover.cc</code> to test that A3 algorithm can perform inter-frequency handover based on A3 event measurements. Run it with <code>./test.py -s lte-secondary-cell-handover</code>

* [https://codereview.appspot.com/328170043/ Phase 2 and 3 code review]

= Project summary =

In this section I briefly describe what I have done according to [https://developers.google.com/open-source/gsoc/help/work-product Work Product Submission Guidelines].

In the project I have implemented handover to secondary cell in NS-3 LTE model with enabled carrier aggregation. The project was divided into three milestones:

# Make UE (User Equipment) receive configuration via RRC (Radio Resource Control) protocol and test the ability of UE to attach to any component carrier of eNB (Enhanced Node B) and receive configuration in runtime.
# Make it possible to trigger manual handover in inter/intra-eNB and inter/intra-frequency cases. Test that handover is successfully performed.
# Make it possible to collect measurements from secondary cells and perform automatic handover to secondary cell based on received measurements.

At this point all the planned milestones are reached. First milestone code is already merged upstream, second passed review and third is prepared for merge and submitted for review.

== Future work ==

Although all the planned work is done, here is a list of things that I plan to do after GSoC:

* Resolve any comments that may arise during code review and merge phase 2 and phase 3 code upstream.
* Fix a [https://www.nsnam.org/bugzilla/show_bug.cgi?id=2754 noncritical bug] I discovered in RRC message serialization during project implementation.
* Implement A6 event measurements. A6 event is triggered when some neighbor cell becomes better than secondary cell. A6 event configuration is transmitted in ASN.1 extension and [https://code.nsnam.org/index.cgi/ns-3-dev/file/a39655894155/src/lte/model/lte-asn1-header.cc#l309 serialization of extensions is not supported by NS-3 ASN.1 code yet], so it is impossible to implement right now and requires ASN.1 serialization API changes.

GSOC2017Lte

2017-08-28T01:14:04Z

Krotov: /* Phase 3 (July 28, 2017 - August 21, 2017) */

GSOC2017Lte

2017-08-27T23:36:04Z

Krotov:

GSOC2017Lte

2017-08-27T06:45:45Z

Krotov: Updated phase 1 and phase 2 sections, added empty final report section

Summer Projects

2017-08-26T23:25:46Z

Krotov: /* Phase 2 reports */ s/Phase 1/Phase 2/

{{TOC}}

The project coordinates a few summer coding programs in which student developers are paired with mentors to produce code over the summer.

= European Space Agency Summer of Code in Space (SOCIS) 2017 =

ns-3 has been accepted to the 2017 ESA Summer of Code in Space, with student Pasquale Imputato

* [[SOCIS2017 | project page]]

The original project ideas page is posted below.

* [[SOCIS2017Projects#Project_Ideas | Project Ideas page]]

= Google Summer of Code 2017 =

The project has been accepted to the 2017 edition of [https://developers.google.com/open-source/gsoc/ Google Summer of Code].

* [[GSOC2017AcceptedProjects | Accepted Projects]]

== Phase 2 reports ==

* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014038.html BCube and FatTree topology helpers (component of TCP Prague project)]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-August/014054.html Implementation of TBF and HHF]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014047.html Enabling LTE CA handover to secondary cell, Phase 2]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014042.html ns-3 App Store]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014049.html Mobile IPv6 implementation with LTE support (report)]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-August/014058.html Mobile IPv6 implementation with LTE support (review request)]

== Phase 1 reports ==

* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013980.html Data Center TCP (component of TCP Prague project)]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013982.html Implementation of TBF and HHF traffic control]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013983.html Enabling LTE CA handover to secondary cell, Phase 1]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013985.html ns-3 App Store]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013987.html Mobile IPv6 implementation with LTE support]

== Background ==

Below is some information that was used during the application phase.

* [[GSOC2017Projects | Project Ideas Page]]
* [[GSOC2017StudentGuide | Student Application Guide]]

= European Space Agency Summer of Code in Space (SOCIS) 2016 =

ns-3 had one student (Michael Di Perna) successfully complete the 2016 [http://sophia.estec.esa.int/socis/ ESA Summer of Code in Space].

* [[SOCIS2016 | Project page]] for Optical Satellite Systems project
* [[SOCIS2016Projects#Project_Ideas | Project Ideas page]]

= Mentored summer projects 2016 =

ns-3 maintainers will mentor additional summer projects (that students will work on using their own sources of funding) on a best-effort basis. Students interested in this option should review the GSoC or SOCIS ideas page, or propose their own.

* See [[MentoredProjects2016]]

= Google Summer of Code 2016 =

ns-3 was not selected for the 2016 [https://developers.google.com/open-source/gsoc/ Google Summer of Code]. We mentored two summer projects outside of GSoC. Below were our materials prepared for our GSoC organizational application.
* [[GSOC2016Projects | Project ideas page]]
* [[GSOCStudentGuide | Student guide]]

= Google Summer of Code 2015 =

ns-3 was selected to participate in the 2015 [http://www.google-melange.com/gsoc/homepage/google/gsoc2015 Google Summer of Code]. More information can be found on our Project Ideas page and our Student Guide.

* [[GSOC2015AcceptedProjects | Accepted projects]]
* [[GSOC2015Projects | Project ideas page]]
* [[GSOC2015StudentGuide | Student guide]]

This year's students were announced on April 27, and all four successfully completed the program:

* Melchiorre Danilo Abrignani, [[GSOC2015LTECA | Carrier Aggregation support for the LTE module]]
* Matthieu Coudron, [[GSOC2015MpTcpImplementation | Implementing multipath TCP (MPTCP) in ns3]]
* Natale Patriciello, [[GSOC2015TCPTest | TCP layer refactoring with automated test on RFC compliance and validation]]
* Vishwesh Rege, [[GSOC2015LrWpanMac | 802.15.4 realistic MAC and Energy Model]]

= European Space Agency Summer of Code in Space (SOCIS) 2015 =

ns-3 has been accepted to the 2015 [http://sophia.estec.esa.int/socis2015/ ESA Summer of Code in Space]. The ns-3 project had one student in SOCIS in each of 2013, 2014 and 2015. However, the satellite channel models project for 2015 [[SOCIS2015 | Satellite channel models]] did not successfully complete.

* [[SOCIS2015Projects | Project ideas page]] (for reference)

= Mentored summer projects =

ns-3 maintainers will mentor additional summer projects (that students will work on using their own sources of funding) on a best-effort basis. Students interested in this option should review the GSoC or SOCIS ideas page, or propose their own.

We have one such mentored project in 2015:

* Saswat Mishra, [[NeighborDiscoveryProject | Neighbor Discovery enhancements]]

= Past summer projects =

* [[GSOC2014AcceptedProjects | GSoC 2014 Accepted Projects]]
* [[SOCIS2014TCP | SOCIS 2014 Accepted Project]]
* [[MentoredProjects2014 | 2014 Mentored Projects]]
* [[SOCIS2013BundleProtocolProject | SOCIS 2013 Accepted Project]]
* [[GSOC2013AcceptedProjects | GSoC 2013 Accepted Projects]]
* [[GSOC2012AcceptedProjects |GSoC 2012 Accepted Projects]]
* [[NSOC2011AcceptedProjects |NSoC 2011 Accepted Projects]]
* [[GSOC2010AcceptedProjects |GSoC 2010 Accepted Projects]]
* [[GSOC2009AcceptedProjects |GSoC 2009 Accepted Projects]]
* [https://developers.google.com/open-source/soc/2008/?csw=1#ns3 GSoC 2008 Accepted Projects]

GSOC2017Lte

2017-05-27T16:11:26Z

Krotov: /* Phase 1 (May 30, 2017 - June 30, 2017) */

GSOC2017Lte

2017-05-16T16:24:45Z

Krotov: /* Technical Approach */

GSOC2017Lte

2017-05-15T22:15:46Z

Krotov:

Tools

2017-04-28T17:55:00Z

Krotov: /* WiFi */ Rename WiFi section to Wi-Fi

{{TOC}}

This page is for linking other useful projects/tools that can be used with ns-3.

= TCP =

* Ohio University's [http://tcptrace.org tcptrace] is useful for TCP checking.

= Wi-Fi =

* An ns-3 port of [http://yavista.sourceforge.net/index.php/Main_Page yavista] would be welcome. '''Note:''' Morgan Redfield at University of Washington started to work on this but the project was suspended; code is archived here: http://code.nsnam.org/redfieldm/ns-3-dev-yavista2/. Someone else is welcome to pick it up.

= Plotting =

*[http://matplotlib.sourceforge.net/ Matplotlib] can be used with ns-3 python programs.

= Topology generators =

ns-3 has support for these tools (in src/contrib/topology-read:
* [http://www.sysnet.ucsd.edu/~pmahadevan/topo_research/topo.html Orbis]
* [http://topology.eecs.umich.edu/inet/ Inet]
* [http://www.cs.washington.edu/research/networking/rocketfuel/ Rocketfuel]

= Mobility scenario generators =

* ns-2 setdest
* [http://net.cs.uni-bonn.de/wg/cs/applications/bonnmotion/ BonnMotion]

= Trace analysis =
* [http://www.tracemetrics.net TraceMetrics] TraceMetrics is a trace file analyzer for Network Simulator 3 (ns-3).
The main goal is to perform a quick analysis of the trace file produced by ns-3's simulations and calculate useful metrics for research and performance measurement.