ns-o-ran-flexric

Project Introduction

Given the importance of obtaining a capable and fully open-source platform for xApp operation testing, especially for the complex use-cases. Orange Innovation Egypt(OIE) team Successfully integrated FlexRIC from EURECOM with ns-O-RAN simulator that originally developed by the institute for the Wireless Internet of Things (WIoT) and Mavenir. The team updated the ns-O-RAN simulator to be a fully compliant with E2AP v1.01, KPM v3 and RC v1.03. This platform will pave the way to test the use-cases that need a rich LTE/5G simulator to be verified. What's more, we propose Graphical User Interface for ns3 which allows to run and observe simulations in user-friendly way. The original project of ns-O-RAN in OpenRAN-Gym.

Project Explanation and Demo

Code Structure

The ns-O-RAN is composed by three main components, as shown in the figure below:

• The e2sim software, which was originally developed by the OSC community.
• The ns3-mmWave version, which was originally developed by the University of Padova and NYU.
• The ns-O-RAN module, developed by Northeastern University and Mavenir, which is basically an external module that can be plugged in ns-3 and uses the e2sim to create a SCTP connection with the RIC.

Main Updates

The implemetation of the E2APv1.01 includes:

1. E2 Setup request

   - Edit the RAN Function IDs for KPM and RC ​
   - Reformat the size of the message to match FlexRIC (62 byte)​
   - Update the KPM description and model to KPM v3 
   - Upda​te the RC  description and model to RC v1.03
   - Add RIC styles 4 
   

2. E2 Subscription Response ​

   - Add RAN Function NotAdmitted IE to the message​
   - Update the message to match KPM v3.0​
   - Fill New RIC indication messages formats (Format 3 )​
   

3. RIC Control Acknoweldege ​

      - Implemented from scratch
   

4. RIC Control Request ​

      - Update the message to match E2SM RC v1.03
   

5. RIC Subscription delete request/response

   - Implemented from scratch
   

6. RIC Subscription modification response (In-Progress)

    - Implemented from scratch
   

7. RIC Subscription modification confirm (In-Progress)

    - Implemented from scratch
   

The implementation of KPM and RC

1. Update the KPM ASN and model to KPM v3.00

2. Update the RC ASN and model to RC v1.03

New ns-3 features

1. '--E2andLogging=(bool)' allows to trace KPIs do file and E2 term in the same time, every "Indication period" KPIs are sent to E2 termination (RIC) and saved to files (CU-CP, CU-UP, DU)

2. New scenario "scenario-zero-with_parallel_loging.cc" as example of use '--E2andLogging=(bool)'

3. Cell deep-sleep implementation (In-Progress)

4. New run flags:

  --KPM_E2functionID=(double)
  --RC_E2functionID=(double)
  --N_MmWaveEnbNodes=(uint8_t)
  --N_Ues=(uint32_t)
  --CenterFrequency=(double)
  --Bandwidth=(double)
  --IntersideDistanceUEs=(double)
  --IntersideDistanceCells=(double)

Graphical User Interface (GUI) for ns3

1. Observe Cell/UEs KPIs

2. Run simulation from GUI with selection of simulation parameters

3. Stop simulation

4. Observe cell allocation and UEs positions

5. Grafana platform deployed to observe simulation results (in-progress - users need to declare InfluxDB queries themselves)

Requirments

First start with the installation of the prerequisites. In Ubuntu 20.04 LTS, these can be installed with:

sudo apt-get update
# Requirements for e2sim
sudo apt-get install -y build-essential git cmake libsctp-dev autoconf automake libtool bison flex libboost-all-dev 
# Requirements for ns-3
sudo apt-get install g++
sudo apt install python3.13 # (or ealier version, but 3.6+ required)

For GUI, Docker Compose is needed, to install it please follow docs.docker.com.

Installation Instructions

The prepation of enviroment for running testing examples can be done when 'near-RIC' is initialized, as sequence diagram is represented below:

1. FlexRiC Installation Instructions

The ns-O-RAN-flexric project is utilizing the latest stable commit of FlexRIC in the dev branch. You MUST adhere to the installation and deployment guidelines outlined under commit number 5bca8030 before use the simulator.

For the FlexRIC installation instructions, once you reach section 1.3, note that FlexRIC is configured to build the nearRT-RIC with E2AP v2.03 and KPM v2.03 by default. However, the ns-O-RAN simulator uses E2AP v1.01 and KPM v3.00. After completing the mentioned installation prerequisites, so you should execute the following commands:

git clone https://gitlab.eurecom.fr/mosaic5g/flexric.git && cd flexric

git checkout dev && git checkout 5bca8030

mkdir build && cd build && cmake .. -DE2AP_VERSION=E2AP_V1 -DKPM_VERSION=KPM_V3_00 && make -j8

Finally, to install the Service Models (SM) on your machine, use:

sudo make install

2. ns-O-RAN-flexric Installation Instructions

First you need to clone the project

git clone --recurse-submodules https://github.com/Orange-OpenSource/ns-O-RAN-flexric

Note

If you made a clone before and there are new updates so you need to make recursive pull

git pull --recurse-submodules https://github.com/Orange-OpenSource/ns-O-RAN-flexric

When checkout to any branch, to ensure you assiocated submodule branch

git config --global submodule.recurse true
git checkout <branch_name>

or

git checkout <branch_name>   && git submodule update --init --recursive

To set up the environment for ORAN E2 simulator, navigate to the /e2sim-kpmv3/e2sim directory. Create a new directory named build. Then execute the script build_e2sim.sh with the argument 3 to enable LOG_LEVEL (DEBUG). This is useful to debug the exchange of the messages between the ns-3 and the RIC, but also there are a different debug levels that can be setup. These levels are summarized in the table below.

cd /e2sim-kpmv3/e2sim/
mkdir build
sudo ./build_e2sim.sh 3

Log Level e2Sim	Value	Description
LOG_LEVEL_UNCOND	0	Show only the uncoditional logs.
LOG_LEVEL_ERROR	1	Show all the previous logs plus failures on the e2Sim side (such as errors on encoding)
LOG_LEVEL_INFO	2 (default)	Show all the previous logs plus the some info about the size of the messages
LOG_LEVEL_DEBUG	3	Show all the possible logs including the xer_printing of the ASN1.C messages

Navigate to ns3-mmWave project:

cd ns-3-mmwave-oran

At this step the software in place to configure and build ns-3:

./waf configure
./waf build

3. GUI deployment

cd ns-3-mmwave-oran/GUI
nano docker-compose.yml # you need to set 'NS3_HOST' IP which is address of machine where ns3 is deployed '- NS3_HOST=192.168.100.21'. This information is needed for control of ns3 from GUI.
docker-compose up --build -d # this will deploy environement which includes GUI and InfluxDB database with newest images
pip3 install influxdb

Usage/deployment

Scenario Zero

Finally, run an example ns-3 scenario called Scenario Zero for testing purpose. This scenario features a Non-StandAlone (NSA) 5G setup in which, its have one LTE eNB positioned in the center of the scenario and four gNBs around it with an inter site distance of 1000 between the eNB and each gNB. You can run the scenario after done the following steps first:

1. First you must be done the installation instructions for the flexric mentiond in the above section 'FlexRiC Installation Instructions'
2. Second you must done the building steps for ns3-oran simulator section, to build an 'e2sim' and 'ns-3-mmwave-oran' waf.
3. The last thing, after you done the building process, it's time to run the scenario-zero as a first test case.
   1. Navigate to '/path/to/flexric/build/examples/ric/' and then run './nearRT-RIC'.
   2. Navigate to '/path/to/ns-3-mmwave-oran' and then run './waf --run scratch/scenario-zero.cc'
   3. Navigate to '/path/to/flexric/build/examples/xApp/c/kpm_rc' and then run './xapp_kpm_rc'.

And if everything goes as intended we should be able to see in order the following messages as shown in the Wireshark snapshot below:

1. E2 Setup Request (ns-O-RAN to E2 Term on RIC)
2. E2 Setup Response (E2 Term on RIC to ns-O-RAN)
3. E2 Subscription Request (xApp to ns-O-RAN through E2 Term on RIC)
4. E2 Subscription Response (ns-O-RAN to xApp through E2 Term on RIC)
5. RIC Indication (ns-O-RAN to xApp through E2 Term on RIC)
6. RIC Control Request (xApp to RIC to ns-O-RAN)
7. RIC Control Ack (ns-O-RAN to xApp through E2 Term on RIC)
8. RIC Subscription Delete Request (xApp to RIC to ns-O-RAN)
9. RIC Subscription Delete Response (ns-O-RAN to xApp through E2 Term on RIC)

Run RIC-TaaP Studio

1. First you need to run script 'python3 gui_trigger.py' in 'ns-3-mmwave-oran' folder, which will be responsible to push ns3 KPIs to database
2. In your browser, type 127.0.0.1:8000 or 'NS3_HOST':8000 (e.g 127.0.0.1:8000).
   It take up to 5 minutes to deploy portal, depends on HW.
3. Click on webpage 'Show form', choose run flags values and click 'Start', you should see Cells and UEs on grid shortly.
   GUI will run 'scenario-zero-with_parallel_loging.cc' with user defined run flags.
   Runtime logs from ns-3 will be saved in 'ns-3-mmwave-oran/ns3_run.log' file.
4. To see current KPIs, click 'Source Data'. If FlexRIC connection is enabled, GUI KPIs will refresh only when xApp is running and Indication messages are exchanged.
   If FlexRIC is disabled in GUI, GUI KPIs will refresh every 1s.
5. To stop simulation, click 'Stop' on 'Show Form' window.
6. To close GUI if not needed, please use command 'docker-compose down' in 'ns-3-mmwave-oran/GUI' folder.

7. [Optional Step] If you would like to observe KPIs from Grafana, which allows to observe past simulations, check the next section.

Observe KPIs with Grafana

1. Grafana is being deployed together with GUI through Docker Compose.
   
2. It can be accessed by typing 127.0.0.1:3000 or 'NS3_HOST':3000 in the browser.
   
3. Choose 'Dashboards' on the left sidebar and then click 'Manage'.
   
4. Here you can choose 'per_Cell_stats' or 'per_UE_stats'.
   
5. Remember to set correctly observation time period in the right corner of the Grafana.
   
6. You can also set auto-refresh in the right corner of the Grafana.
   
7. List of all available KPIs that can be get with query can be found in '/docs/Grafana KPIs'.

Further Resources

Participation in 10th OpenAirInterface Anniversaray Workshop

• RIC Testing as a Platform Demo Architecure : Full Architecture
• FlexRIC Community Announcement: GitLab Link
• OAI Demo Brochure: Link
• OAI Demo Video: OpenAirInterface 10th Anniversary Workshop
• KPM-RC xApp Demo: YouTube Link

Contributers

• Mina Yonan, Orange Innovation Egypt, [email protected]
• Mostafa Ashraf, Orange Innovation Egypt, [email protected]
• Kamil Kociszewski, Orange Innovation Poland, [email protected]
• Adrian Oziębło, Orange Innovation Poland, [email protected]
• Abdelrhman Soliman, Orange Innovation Egypt, [email protected]
• Aya Kamal, Orange Innovation Egypt, [email protected]
• Bartosz Rak, Orange Innovation Poland, [email protected]

Liscence

GNU GENERAL PUBLIC LICENSE