Revision as of 13:04, 12 June 2023

Back to GSoC 2023 projects

Project Overview

• Project Name: IUNS-3 5G NR: Improving the Usability of ns-3's 5G NR Module
• Student: Giovanni Grieco
• Mentors: Tom Henderson, Katerina Koutlia, and Biljana Bojovic
• Google page: https://summerofcode.withgoogle.com/programs/2023/projects/oeDFknbT
• Project Goals: IUNS-3 5G NR is a GSoC '23 medium-size project proposal that offers a general purpose introductory scenario to dive into the 5G New Radio world, unlocking the ability for users, from university students to research scientists and engineers, to know the 5G architecture in detail and enable them to use the simulator for research and development.
• Repositories:
  • https://gitlab.com/ggrieco/ns-3-dev - ns-3 personal fork
  • https://gitlab.com/ggrieco/nr - NR module personal fork
• About Me: I am a second-year PhD Student in Electrical and Information Engineering at Polytechnic University of Bari, Italy, focused on Telecommunications Engineering and, more specifically, the Internet of Drones. ns-3 orbited so much around my university career, as I have been developing IoD-Sim, a ns-3 module for the Internet of Drones, since my bachelor's final thesis in 2019. ns-3 still remains my primary tool to test out experimental protocols, applications, and communication technologies that would otherwise require very expensive infrastructure to reproduce in the laboratory. This Google Summer of Code project represents a unique opportunity to better know the community, learn from their experiences, and contribute my ideas to upstream!

Milestones

Week 1

1. Read 3GPP TR 38.300 as an overview. In general, we will look to align with 3GPP terminology and specifications.
2. Start to document somewhere (Google doc, or Sphinx) the lifecycle of these UDP packets-- what are the interesting things that happen to each packet to get it through the RAN?
3. Start to migrate LOG statements so that interesting logs are in NS_LOG_INFO and NS_LOG_WARN. See WifiHelper::EnableLogComponents()-- we should come up with a similar one for NrHelper::EnableLogComponents (level=INFO by default). Alternative is to place dedicated methods in the nr examples, tailored to logs of interest.
4. Enable traces: //nrHelper->EnableTraces(); perhaps controlled by a command line argument. How can these help the new user?
5. Line 453 of cttc-nr-demo.cc states: // From here, it is standard NS3. In the future, we will create helpers for this part as well. Start to create such helpers, focusing first on application and TFT configuration.
6. Start to experiment with the ConfigStore loading and saving of attributes and default values.
7. Measuring latency within the NR RAN-- new trace sources at ingress and egress of NetDevice? Packet tags?

Weekly Report

Week 1 [May 29 - Jun 03]

• Tracking ns-3 3.38 release and NR 5g-lena-v2.4.y branch
• Milestone 5 is tracked over MR 52
• Some compile-time deprecation/warnings were addressed in MRs 48 and 49
• Minor fixes made in MRs 50, 51, 53

Week 2 [Jun 05 - 10]

Started the analysis of `cttc-nr-demo` to probe around usability issues and what I can do to solve them.

Initial Doxygen comments - lines: 7-29

 This example describes how to setup a simulation using the 3GPP channel model from TR 38.900.

The 3GPP TR 38.900 is part of Release 15 regarding the Study on channel model for frequency spectrum above 6 GHz. It is freely available at the 3GPP Portal and on ETSI as PDF.

First of all, please notice that here we are dealing with a standard that is marked as obsolete, as per comment by John M Meredith make in 2018:

 This spec is not maintained after v15.0.0. It is superseded by 38.901.

which is the Study on channel model for frequencies from 0.5 to 100 GHz and it is available on the 3GPP Portal.

So, first of all, are we sure that we are working on code that provides the latest standard implementation Out of the Box? A quick search

 $ grep -ri 'TR 38.900' contrib/nr | wc -l
 16
 $ grep -ri 'TR 38.901' contrib/nr | wc -l
 9

reveals that the module has been updated to support the more recent TR 38.901.

 This example consists of a simple grid topology, in which you can choose the number of gNbs and UEs. Have a look at the possible parameters to know what you can configure through the command line.

First of all, there is a small typo on "gNb", as it should be written as gNB. This term is defined in TS 38.300:

gNB: node providing NR user plane and control plane protocol terminations towards the UE, and connected via the NG interface to the 5GC

This is not the only part where gNB is spelled wrongly:

 $ grep -r 'gNb' contrib/nr/ | wc -l
 423

Furthermore, here we talk about the "command line". There is no reference of how such command line interface works in the NR official manual, neither in the repository README.md file. Only the doxygen documentation reports examples of how its syntax, but such information is not readily available for the novel user.

With the default configuration, the example will create two flows that will go through two different subband numerologies (or bandwidth parts). For that, specifically, two bands are created, each with a single Carrier Component (CC), and each CC containing one bandwidth part (BWP).

Here we use some technical terms that are related to specific features of NR. This is aggravate by the fact that we are using technical acronyms, i.e., CC, without writing them in extended form. Unfortunately, a quick search of "subband numerologies", "bandwidth part", and "CC" over the aforementioned TR 38.900 returns no explanation or usage.

Consequently, this paragraph is hard to understand if the user does not already have a broader understanding of the several standards that characterize NR, or 3GPP Release 16 (and higher) in general.

 The example will print on-screen the end-to-end result of one (or two) flows, as well as writing them on a file.

This output appears to be too strict. As it is quite succinct for an experienced user, who may easily imagine the node positions, its stack configuration, its traffic, and the overall network topology. On the contrary, an inexperienced user may expect some context to fully understand these Key Performance Indices (KPIs) and statistics.

 With this line, we will be able to see the logs of the file by enabling the component "CttcNrDemo".

Log components are not explained in the neither in the [README(https://gitlab.com/cttc-lena/nr/-/blob/master/README.md NR official manual].

Code lines 148-153

 /*
  * Check if the frequency is in the allowed range.
  * If you need to add other checks, here is the best position to put them.
  */
 NS_ABORT_IF(centralFrequencyBand1 > 100e9);
 NS_ABORT_IF(centralFrequencyBand2 > 100e9);

According to TR 38.901, we miss the lower bound limit of 0.5 GHz.

Code lines 155-170

 /*
  * If the logging variable is set to true, enable the log of some components
  * through the code. The same effect can be obtained through the use
  * of the NS_LOG environment variable:
  *
  * export NS_LOG="UdpClient=level_info|prefix_time|prefix_func|prefix_node:UdpServer=..."
  *
  * Usually, the environment variable way is preferred, as it is more customizable,
  * and more expressive.
  */
 if (logging)
 {
   LogComponentEnable("UdpClient", LOG_LEVEL_INFO);
   LogComponentEnable("UdpServer", LOG_LEVEL_INFO);
   LogComponentEnable("LtePdcp", LOG_LEVEL_INFO);
 }

This information would solve `T9` by anticipating such information.

Code lines 172-176

 /*
  * Default values for the simulation. We are progressively removing all
  * the instances of SetDefault, but we need it for legacy code (LTE)
  */
 Config::SetDefault("ns3::LteRlcUm::MaxTxBufferSize", UintegerValue(999999999));

This does not seem to be entirely related to the example per se, given that it misses key information on why such scenario should have such value to be set. Furthermore, such value is applied across all example scenarios. To this end, it would be better to hide such code from the user eyes, in order to not cause confusion.

Code lines 178-198

 /*
  * Create the scenario. In our examples, we heavily use helpers that setup
  * the gnbs and ue following a pre-defined pattern. Please have a look at the
  * GridScenarioHelper documentation to see how the nodes will be distributed.
  */
 int64_t randomStream = 1;
 GridScenarioHelper gridScenario;
 gridScenario.SetRows(1);
 gridScenario.SetColumns(gNbNum);
 gridScenario.SetHorizontalBsDistance(5.0);
 gridScenario.SetVerticalBsDistance(5.0);
 gridScenario.SetBsHeight(1.5);
 gridScenario.SetUtHeight(1.5);
 // must be set before BS number
 gridScenario.SetSectorization(GridScenarioHelper::SINGLE);
 gridScenario.SetBsNumber(gNbNum);
 gridScenario.SetUtNumber(ueNumPergNb * gNbNum);
 gridScenario.SetScenarioHeight(3); // Create a 3x3 scenario where the UE will
 gridScenario.SetScenarioLength(3); // be distribuited.
 randomStream += gridScenario.AssignStreams(randomStream);
 gridScenario.CreateScenario();

`ns3::GridScenarioHelper` documentation is marked as TODO in the source file. Furthermore, distance, length, and height properties do not provide any unit of measurement. This is aggravated by the lack of any sort of unit to be used in both code (we have a generic `double`) and documentation. Intuitively, the user, which may come from any place of Earth, can be confused on using the International System of Units (SI), the metric system, or the imperial one.

Week 3 [Jun 12 - 17]