How to setup and use our open source ns-O-RAN Open RAN Simulation Platform with a near-RT RIC
ns-O-RAN is the first open source simulation platform that combines a functional 4G/5G protocol stack in ns-3 with an O-RAN-compliant E2 interface. This completes WIoT’s OpenRAN Gym platform with a simulator that can enhance data collection and xApp testing capabilities, a key step toward enabling efficient and generic AI and ML solutions for Open RAN and 5G/6G systems.
ns-O-RAN has been designed and implemented to enable the integration of O-RAN software such as the O-RAN Software Community Near-RT RIC with large-scale 5G simulations based on 3GPP channel models and a detailed modeling of the full 3GPP RAN protocol stack. This allows data collection of RAN Key Performance Metrics (KPMs) at scale, in different simulated scenarios, and with different applications (e.g., multimedia streaming, web browsing, wireless virtual reality, etc). ns-O-RAN supports an O-RAN-compliant E2 interface and implements two E2 service models (E2SM), E2SM-Key Performance Metrics (KPM) monitoring and E2SM-RAN Control (RC), that enable a closed-loop control (for example, of traffic steering and mobility).
In this tutorial, we show how to install and setup ns-O-RAN on your environment and how you can create simulated closed control loops between ns-3 and a Near-RT RIC. For this guide, we use the near-RT RIC from the WIoT’s ColO-RAN framework. Such framework can be installed on your local workstation or can be loaded into any experimental platform such as Colosseum. In this latter case, we already provide a public available LXC image that can be used.
This part of the tutorial requires a working version of Docker for hosting the RIC on your localhost.
We first start by cloning and setup the Colosseum’s near-RT RIC with the following commands:
Then we first import all the images we need in Docker, we tag them properly and we build and launch them:
After the last step, the main entities of the RIC should be up and running in different Docker containers
(this can be easily checked with the
docker ps command).
To understand what is going on in the RIC and to have a feedback once we start ns-O-RAN,
we can open two terminal for the RIC, one for logging the values on the E2Term and check the E2AP messages exchange,
the other for the xApp.
This last command will build and run a Docker container for the x-app and will also create a shell inside the container. Finally, we can mve to the
/home/sample-xapp directory inside the Docker container, and run the xApp logic:
These lasts commands concludes the setup of the RIC. If you already have a working RIC just make sure to annotate the IP address of the E2Term, which is needed to create the connection between ns-O-RAN and the RIC.
To properly install ns-3 and ns-O-RAN, several options are available, including the use of the Dockerfile provided in the root of the near-RT RIC repository. In this part of the tutorial, we will setup and install the ns-O-RAN framework. As described in the related paper and in the Figure above, ns-O-RAN is composed by three main parts:
We adapted the first two software to enable the end-to-end communication with the near-RT RIC and the digestion of the E2AP and E2SM messages. We first start with the installation of the prerequisites. In Ubuntu 20.04 LTS, these can be installed with:
Then we can clone and install the e2Sim software. To see the E2 ASN messages on the e2sim, we build it with LOG_LEVEL equal to 3 (DEBUG). This is useful to debug the exchange of the messages between the ns-3 and the RIC, but we also provide different debug levels that can be setup. These levels are summarized in the table below.
|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|
This last command shall configure the cmake project and install the e2sim on the system. Its main actions are also in the aforementioned Dockerfile that we report here to clarify the operations conducted by the script:
It is now time to clone and install the ns3-mmWave project:
At the time of writing this tutorial, this project supports the 3.36 version of ns-3, thus we still use the old
waf toolchain to configure, build and run ns-3. We plan to upgrade our version of ns-3 in the near future and, as a consequence of this, we will also update the guide. After this step, we can clone the ns-O-RAN module and insert it in the ns3-mmWave project in the
We now have all the software in place to configure and build ns-3:
Finally, we can run an example ns-3 scenario called “Scenario Zero”. This scenario features a Non Stand Alone (NSA) 5G setup in which we 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. We can run the scenario with the command:
And if everything goes as intended we should be able to see in order the following messages flowing between the ns-3 and the RIC:
Check that this situation is happening, we can see the same message in all the three different terminals opened, as shown in the Figure below.
This concludes this tutorial for now. It is in our intention in the nearby future to cover also the creation of custom E2 Service Models (SMs) with ns-O-RAN and the simulated control loop with the exchange of RIC Control messages in the simulated environment. If you use ns-O-RAN in your research, please consider to reference the following paper: