From Nsnam
Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

Return to GSoC 2018 Accepted Projects page.

Project overview

  • Project name: Merging and Improvement of the LTE and Wi-Fi Coexistence Module
  • Abstract: The LTE and Wi-Fi Coexistence Module which implements 3GPP specification of License Assisted Access (LAA) and the interfacing of LTE and Wi-Fi module in ns-3, has been quite popular with ns-3 users. But the current work on the module is far removed from the mainline development, thus missing improvements that has been implemented on the upstream. It is hard to apply patch from upstream to the module, and inversely, merge the module to upstream. Moreover, it is also created to implement TR 36.889 test scenarios, making it difficult to customize for other cases. Furthermore, more improvement ideas can be implemented to streamline and improve readability of the simulation scenario. Some key features missing from the unit test (e.g., LAA backoff), will also be implemented. The goal of the project will be to merge the existing module to be in-line with upstream, improve the usability of the module, and additionally, merge useful improvements that are independent from the LTE-Wi-Fi coexistence to the upstream ns-3-dev.
  • About me: I am an admitted PhD student of the Computer Science Departement of University of Chicago starting next September. Previously, I did my Master Studies at the National Taiwan University of Science and Technology (NTUST), Taiwan. Since my current research focus is on the LTE and Wi-Fi Coexistence, I have taken a large interest in improving the module. I have been working with Tom Henderson for quite some time to merge the module to the upstream, and doing it under GSoC wil hopefully accelerate the progress.

Technical Approach

The goal of this project is to make available to ns-3 users the LTE and Wi-Fi Coexistence module based on the current ns-3. This involves porting and upstreaming changes to the LTE, Wi-Fi, and applications modules, and improving the LAA-related code. The plan is to port the existing code with 3GPP scenario, including tests and documentation, and then if time remaining, to make improvements to the module.

The first step will be modifying the LTE and Wi-Fi modules to better interface the two modules. Some of these modifications have been implemented, for instance: a spectrum-aware PHY model for Wi-Fi; but most of the modifications will be on LTE module: porting the LAA codes to the new carrier aggregation code, implementing HARQ feedback and backoff, and channel access.

In addition to new codes, this preliminary works will also includes fixing bugs (e.g., "bug 2399", "bug 2470") and implementing new requested features (e.g., FileTransferApplication, and roaming capability for Wi-Fi).

After the preliminary modifications, the next step will be merging the current available work of ns-3-lbt repository along with improvements. The current LTE and Wi-Fi Coexistence Module has an addition of "experiments" component which holds scripts for 3GPP TR 36.889 test cases. Because the test cases are similar, those test scenarios are calling ScenarioHelper class in the helper component to set up everything. An improvement to ScenarioHelper is proposed, so that users can modify much more simulation parameters for their own scenario.

The end results will be an improved LTE and Wi-Fi Coexistence Module that is separated but still in-line with upstream. This module will be a contributed extension and hosted at the new ns-3 App Store. Additionally, any improvements that are independent to the LTE-Wi-Fi coexistence case will be merged to the upstream.

Milestones and Deliverables

The GSoC period is divided into 3 phases. The planned deliverables at the end of each phase is as mentioned below. If other contributors can make progress on some of these porting issues, then we can start Phase 3 work earlier.

Phase 1: Wi-Fi and Applications

  • Resolve "bug 2399" on introducing roaming capability to STA Wi-Fi
  • Resolve "bug 2470" on handshake to set up Block Ack Agreement (which leads to zero throughput for some AP/STA combinations)
  • Implementation of FileTransferApplication according to previous works with the addition of FileSrc attribute for adding file input.
  • Any other additional porting and bug fixing necessary to be able to run the Wi-Fi (cell A), Wi-Fi (cell B) scenario.
    • SpectrumWifiPhy support for channels other than 36, 40, 44, and 48 [1].
    • Wifi MAC fails assertion on simulation with many devices [2][3]
    • Problem with tracing dropped packets [4].
    • InterferenceHelper gives negative trace value for Interference Power [5][6].

Phase 2: LTE port

  • Follow the CTTC step-by-step guide for porting the LTE portions of the LAA code to the new carrier aggregation code [7].
  • Test additional parts of the LAA code involving LBT including HARQ feedback and backoff, and channel access.
  • Any other documentation and testing, and bug fixing, necessary to replicate the original functionality of the code.

Phase 3: Finalize

  • Merge the rest of ns-3-lbt, this includes models, examples, helper classes, experiments, and unit tests.
  • Implement LAA backoff test and improve the unit test for LbtAccessManager to include uncovered tests.
  • Improve the flexibility of the ScenarioHelper (or adding new helpers), so that users should be able to modify more parameters from their own scenario, such as:
    • The number of cell group (currently only two cell groups).
    • Different application starting time for each cell.
    • Granularly control each node’s parameter (e.g., LBT TXOP, Minimum and Maximum CW)
  • Finalize documentation and testing for the new module.

Weekly Reports

Community Bonding Phase (April 24th-May 13th)


  • Finalized overall plan and timeline for implementing compability patches for both Wi-Fi and LTE module with mentor.
  • Met and discussed with other collaborator on the LTE compability patches.
  • The plan for the first step of Wi-Fi patch: improvement to the MAC model of Wi-Fi Station has been created. The merge plan can be viewed here.
  • Set up repository for the personal works which can be accessed here
  • Briefed on the steps to request code merge to upstream.

Week 1 (May 14th-May 20th)

Tasks Completed:

  • Reviewed previous patches that was posted to bugzilla [8] [9].
  • Finalized patch plan based on the previous patch review, mentor's and collaborator's feedback.
  • Implemented the patch plan and reviewed it with mentors.
  • Identified problems after the code review, decided to reduce the scope of the bug fix.


The first week of coding phase was spent to implement improvements to the MAC model of Wi-Fi Station and resolve bug 2399. I implemented the finalized patch plan but after discussing the codes with mentors, we identified more problems:

  • The roaming behavior of STA has made the code more complex, the amount of channels that need to be roamed can be large and therefore can make the scanning timeout too long.
  • REFUSED state of StaWifiMac is a dead end, may need to be automatically resolved.
  • ASSOCIATED state should be sticky unless not recoverable: may need to add reassociation procedure on MissedBeacon event.

We then decided on these following steps of patches:

  1. Update documentation based on the current upstream implementation: add information on Wifi docs about current scanning & association process, and update state graph on code.
  2. Refactor sta-wifi-mac.{cc,h} codes for better readability and to prepare for the next patch.
  3. Implement the patch plan without channel roaming, the patch will modify:
    • Wi-Fi docs (wifi-design.rst) with update for behavioral change.
    • sta-wifi-mac.{cc,h} for better handing of REFUSED state: Add list of potential APs from active/passive scan, STA will first try to associate with the AP with best SNR. If failed, then try the next best AP. Only go to REFUSED state when the list is exhausted.
    • Add two unit tests to test the new event handling.

The patch plan has been updated accordingly [10]. Currently, the fix on MissedBeacon handling is pushed for another patch if there is time left on the project.

Week 2 (May 21st-May 27th)

Tasks Completed:

  • Implemented a sequence of 3 patches to resolve bug 2399 [11]:
    1. Updating Wifi documentations to better reflect the current state of infrastructure association on StaWifiMac.
    2. Refactor part of Receive function on StaWifiMac for better readability and to prepare for patch #3.
    3. Improve scanning capability and infrastructure association procedure on StaWifiMac, accompanied with its unit tests.
  • Discussed the patches with mentor and received approval.
  • Posted the patches on bugzilla for community's review [12].


We have improved the scanning procedure of StaWifiMac as follows:

  • Added a scanning state to gather beacons or probe responses. So rather than STA associating to the first beacon/probe response received, it will wait for an amount of time, then associate to the best AP (i.e., the best beacon/probe resp SNR).
  • If the best AP refused STA's association request, STA will try to associate to the next best AP until the list of candidate AP exhausted, if this occur STA will finally go to REFUSED state. Note that we cannot test this behavior since ns-3 haven't implement explicit association refusal from AP.

The patches for the improvements have been given go-ahead by mentor and posted to the bug tracker for community's approval. For the next week, we plan to resolve bug 2470.

Week 3 (May 28th-June 4th)

Tasks Completed:

  • Planned approaches to resolve bug 2470 with mentor.
  • Moved FileTransferApplication from previous works to the experimental branch.
  • Bug 2470: Implemented a regression test to test the response on ADDBA request fail [13].
  • Implemented ErrorModel to WifiPhy as a part of regression test.


To resolve bug 2470, we first implement a regression test to test the device's response when ADDBA request fails. The test involves a simple AP-STA setup with AP as the originator. After STA has associated, AP will try to send a burst of packets and establish BA agreement by sending ADDBA request packet. Using ErrorModel, we marked the ADDBA packet to always drop on recipient. The results is as follows:

  • ADDBA packets does considered as a DATA packet and needs ACK for successful transmission.
  • When missing ACK, ADDBA packet will be retransmitted until MaxSlrc.
  • If MaxSlrc exceeded, the originator stops the whole transmission attempt and the rest of the packets are lost.

From the regression test, we can be confident to say that ADDBA packets are retransmitted on failure following the standard. Yet the lost packets may not be an intended behavior, and we are currently gathering information on how real devices handled this case.

Week 4 (June 5th-June 11th)

Tasks Completed:

  • Merged the solution to bug 2399 to upstream.
  • Proposed solution to bug 2470.
  • Discovered an issue on the usage of SSRC and SLRC that is not aligned to the standard. A bug report has been submitted [14].
  • Discovered a failing Wifi test suite on commit 13643, and found out that it is unrelated to the bug 2399's patch, rather it is caused by unprotected RNG stream of other test in the suite.
  • Imported coexistence module from ns-3-lbt with disabled LTE support [15].


This week we are finalizing the the first phase of the LTE-Wifi Coexistence Module. First, a solution to bug 2470 is proposed: on fail BA agreement, Mac Low layer should notify Mac High layer to resend the packets using normal MPDU. It is pending community's approval.

Secondly, we imported previous coexistence module codes from ns-3-lbt with modifications such that an experiment consisted of entirely Wifi cells can be run. This involves stubbing out part of the code related to LTE.

First Phase Evaluations

As previously planned, we finalized the Wifi module to prepare for the coexistence module. We pushed patch for bug 2399 to upstream and planned for bug 2470. We also successfully imported old coexistence codes to the latest commit. The imported codes stub out codes that related to LTE thus currently only works with Wifi cell. A script to run a Wifi-Wifi simple experiment is implemented to confirm that the module works and outputs logs correctly.

Week 5 (June 12th-June 18th)

Tasks Completed:

  • Implemented NO_REPLY and RESET state to Block ACK agreement [16]


I have a family matter to attend this week and the following week, therefore my progress is slower this week. Meanwhile, we implemented the fix for bug 2470 which proposed last week. We put the BA state to a transitory state where packets will be sent using normal MPDU during that state and reset on the next queued packet. This introduced a bug, thus more fixing is needed.

Week 6 (June 19th-June 25th)

Tasks Completed:

  • Fixed AddBaTest bug
  • Added ADDBA handing to handle cases of missing ACK of ADDBA request and missing ADDBA response
  • Added more documentation on the state flow of BA agreement
  • Implemented patch #1 of the LTE patch plan [17]


This week, we start to work on the LTE patch plan. We implemented patch #1 but with a change: put the modifications on DoSchedDlTriggerReq on PfFfMacScheduler on patch #3 since it is dependent on that patch.

Meanwhile the patch for 2470 is almost ready with more fixes and documentations. It will be finalized after review from mentors.

Week 7 (June 26th-July 1st)

Tasks Completed:

  • Finalized and rebased bug fix 2470 [18].
  • Submitted bug fix 2470 to the tracker [19].
  • Found a bug to the bugfix of 2926, reopened the bug tracker and submitted the fix [20].
  • Fixed and rebased the experimental lbt-wifi branch [21].


This week we fixed the experimental lbt-wifi branch which contains imported codes from ns-3-lbt with some code blocks stubbed out so it can run a Wifi-Wifi scenario. We fixed the commits' title and restored FileTransferAppication to the original version. We will then submit some commits from this branch to the gsoc-next staging branch.

On bug 2926, we found out that the SSRC and SLRC increment/reset behavior is still not fixed. The model was still incrementing/resetting SSRC for RTS frames and SLRC for DATA frames. We have submitted a patch and reopened the submission.

And for the fix to bug 2470, we have finalized and rebased it to the latest upstream commit, and submit it to the tracker.

Week 8 (July 2nd-July 8th)

Tasks Completed:

  • Rebased the LTE merge plan branch to the latest commit of master.
  • Implemented LTE merge plan up to point number 3.
  • Implemented the previously stubbed DoIsThereData function for the FF MAC schedulers [22].
  • Closed bug 2926.


This week, we continued on the LTE merge plan up to patch 3 of 11. In addition we also rebased the branch to the latest commit of master, and implemented the previously stubbed DoIsThereData function for the rest of FF MAC schedulers.

We started to collaborate with a student from Huazhong University of Science and Technology, China. They are willing to work on the LTE merge plan and showed their current work so far. After checking their work, we agreed to continue the patch plan from my branch.

On the other hand, we have been discussing to merge some commits that are independent of the LTE-Wifi Coexistence module into the gsoc-next branch. The commits to be merged are commits from the LTE merge plan, and the first four commits of the experimental Wifi-Wifi coexistence branch [23]. Tom will finish the documentation and unit test for VoiceApplication [24] so it can also be merged.

Second Phase Evaluations

We planned to finish the LTE merge plan on the second phase evaluation, but due to incomplete tasks left from the previous phase, we are missing the deadline. The fix to bug 2470 is more complex than previously thought and taking more development time than planned. Also, the discovery of new bugs has taken the time from working on LTE merge plan. Fortunately, we have started a collaboration with a student from Huazhong University of Science and Technology, China for the merge plan. Hopefully, it will speed up the development process.

Week 9 (July 9th-July 15th)

Tasks Completed:

  • Reworked bug 2470 fix from community's comments [25].


Due to personal circumstances, this week I only managed to complete one task. I have reworked the bug 2470 fix based on the comments and submitted it for further review.

Week 10 (July 16th-July 22nd)

Tasks Completed:

  • Opened issues on Bugzilla to mainline some small API extensions to network and wifi module to facilitate the coexistence module [26][27][28].
  • Went ahead and implemented the later patches from the LTE merge plan; currently 6 out of 11 patches completed [29].


The collaboration with HUST student went slower than expected, therefore we went ahead and implemented the later patches from the merge plan. On our repository, 6 out of 11 patches has been implemented (no. 1-3, 8-10). The HUST student claimed the patch 4 and 5 has been implemented and currently working on patch 6. In total, there are possibly 8 out of 11 patches completed.

On the other hand, we have submitted patches for review on Bugzilla to mainline some small API extensions to network and wifi module to facilitate the coexistence module. These patches are previously implemented on the experimental LBT-Wifi branch [30].

Week 11 (July 23rd-July 29th)

Tasks Completed:

  • Implemented patch 6 [31] and 7 [32] of the LTE merge plan.


This week we implemented patch 6 and 7 of the LTE merge plan, bringing the count to 10 out of 11 patches possibly completed. We received a patch from the student we collaborated with [33], but we haven't merge it yet. Next, we will be working on the last patch and importing the rest of the laa-wifi-coexistence module of ns-3-lbt repo.

Week 12 (July 30th-August 6th)

Tasks Completed:

  • Updated LTE plan branch [34] with the remaining of the patches in correct order.


This week, we completed the LTE merge plan and submitted it to the mentors for evaluation. Next we will import the rest of laa-wifi-coexistence module from ns-3-lbt, which includes examples, unit tests, and experiments.

Final Submission Week (August 7th-August 14th)

Tasks Completed:

  • Imported the rest of the module form old ns-3-lbt repo to the experimental lte-wifi branch [35]
    • Imported propagation loss model from ns-3-lbt [36]
    • Imported and fixed unit tests [37]
    • Imported the rest of examples [38]
    • Imported the rest of experiments [39]


This week we wrapped up the development on the module by importing the rest of the code. This includes fixing the code so it can work on the current ns-3-dev.

GSoC 2018 Wrap Up and Final Evaluations

Google Summer of Code 2018 wrapped up on Aug 14, 2018. It has been an interesting experience to work on an open source project during this summer. During the project, I learned about how important it is to communicate when collaborating on an open source project. Because of good communications with mentors, even though the project proves to be more challenging than anticipated, we are able to finish within the reasonable goals.

Project Summary and Final Report

The LAA-Wifi Coexistence Module is module that aims to implement a coexistence between LTE and Wi-Fi infrastructure. It was a popular module for users, but hard to work with due to being implemented on a repository widely separated from the upstream ns-3-dev development repo. For example, it was hard and costly to patch a bug on the module even if it has been fixed upstream, since the patch needs to be individually applied (as opposed to automatically merged).

Hence, there is a need to port the coexistence module to the latest ns-3-dev line. I proposed this GSoC 2018 project for that reason, along with fixing and improving the module specifically, and the whole project overall. The module is renamed to LTE-Wifi Coexistence, as it will serve as the general implementation for LTE and Wi-Fi coexistence (currently, there are two competing standards for the coexistence scenario: LTE-LAA and LTE-U, we aim to implement both on this module in the future). At start, we planned three milestones. At the first phase we aim to fix Wi-Fi bugs that are related to the module. At the second phase, the LTE module is improved to prepare for the coexistence module. Lastly, we proceed to import the existing module codes and improve the flow of scenario in the module.

Phase 1

In phase 1, we have proposed fixes to several bugs in Wi-Fi module that are related to the coexistence module, those are:

  • Bug 2399 which improves the scanning capability of STA. This is intended to fix Wi-Fi STAs that cannot associate to AP on a dense scenario in the coexistence module
  • Bug 2470 which introduces protection to the ADDBA handshake. This may fix bugs on the coexistence module where zero throughput is produced on Wi-Fi cells.
  • Bug 2926 which fixes SSRC and SLRC usage that was not aligned to the standard. This bug was found while working on the project and was not planned on the proposal to be fixed.

This phase took three weeks longer than expected, since there are reviews and revisions for every bug entry that I worked on. I managed my time by working on other things while waiting for review, but it still took longer than planned. While I was frustrated by how slow the review process is, I understood it is very important and fundamental for an open source project.

You can view all of the works that has been done on phase 1 on the following link. Note that since each individual patch are subject to its own review, they are introduced to the master branch at a different time. This difference may cause the code to not work as intended, therefore this branch is intended for archival purposes only. Link to phase 1 branch:

Phase 2

In phase 2, we implemented the CTTC LTE step-by-step guide for porting the LTE portions of the LAA code to the new carrier aggregation code [40]. This merge plan is intended to prepare the LTE module for coexistence scenarios. It includes:

  • Improvements to LTE schedulers [41][42].
  • Extended support for channel 40, 52, and 55 [43].
  • Support for Almost Blank Subframe (ABS) [44].
  • Added channel access manager for LTE [45][46] and DRS control message [47].
  • And other general improvements.

Due to phase 1 that took a longer time, I worked on phase 2 concurrently with other phases from week 6 to 11. Fortunately, since it is a single issue, I only need to report once for that issue. On this phase we were collaborating with a student from HUST to expedite the process. But due to lack of communication, I was confused about what the other side has worked on. The student apparently has become busy during the project and could only contribute a commit.

Link to phase 2 branch:

Phase 3

In phase 3, we imported the laa-wifi-coexistence module from the old ns-3-lbt repository. We planned to first implement small miscellaneous improvement for other modules. We then import the old codes with LTE parts stubbed, and confirm that a Wifi-Wifi scenario can be run. Next, we import the rest of the code, run the tests and examples, and fix it if needed. There are some general improvements that may be pushed upstream:

  • Miscellaneous improvements to Wi-Fi and Network module [48][49][50].
  • Added Gain attribute to IsotropicAntennaModel [51].
  • Added new propagation loss models [52].
  • Added new applications [53][54].

I worked on the third phase with less time than planned, therefore the plan to improve the scenario flow cannot be fit into the schedule. I discussed with my mentor and we set a reasonable goal to import the existing code and make sure that the test passed and the experiments can be run.

Link to phase 3 branch:


Code statistics for phase 1:

git diff d9f77b2 gsoc_phase1_final --stat
35 files changed, 1533 insertions(+), 609 deletions(-)

Code statistics for phase 2:

git diff cef14b9 gsoc_phase2_final --stat
64 files changed, 2476 insertions(+), 334 deletions(-)

Code statistics for phase 3:

git diff gsoc_phase2_final gsoc_phase3_final --stat
99 files changed, 238467 insertions(+), 9 deletions(-)

Backlogs and Future Works

This project accomplished the main goal of porting the LAA Wi-Fi coexistence module to the latest ns-3 mainline, and fixed some bugs in the mainline along the way, but there remain some additional improvements that are being tracked for future work:

  • Check the correctness of the simulation.
  • The FileTransferApplication and VoiceApplication are missing unit tests and documentation.
  • Implement LAA backoff test and improve the unit test for LbtAccessManager to include uncovered tests.
  • Improvement to the flexibility of the ScenarioHelper (or adding new helpers), so that users should be able to modify more parameters from their own scenario.
  • Fix bugs that was reported to the issue tracker [55].
  • Additional fixes for issues that was reported by users:
    • SpectrumWifiPhy support for channels other than 36, 40, 44, and 48 [56].
    • Wifi MAC fails assertion on simulation with many devices [57][58]
    • Problem with tracing dropped packets [59].

After the GSoC project ended, I still plan to contribute to the module. I and my mentor agreed to focus on addressing the correctness of the simulation and the bug reports after the project.