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.

Near-RT RIC Setup

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:

git clone -b ns-o-ran https://github.com/wineslab/colosseum-near-rt-ric
cd colosseum-near-rt-ric/setup-scripts

Then we first import all the images we need in Docker, we tag them properly and we build and launch them:

./import-wines-images.sh  # import and tag
./setup-ric-bronze.sh  # setup and launch

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.

# Terminal 1 logs the E2Term
docker logs e2term -f --since=1s 2>&1 | grep gnb:  # this will help to show only when a gnb is interacting

# Terminal 2 builds and run the x-app container
cd colosseum-near-rt-ric/setup-scripts
./start-xapp-ns-o-ran.sh

This last command will build and run a Docker container for the x-app and will also create a shell inside the container, and log you inside the container. Finally, we can move to the /home/sample-xapp directory inside the Docker container, and run the xApp logic:

cd /home/sample-xapp
./run_xapp.sh

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.

ns-O-RAN Setup

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:

• 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.

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:

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++ python3

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.

git clone https://github.com/wineslab/ns-o-ran-e2-sim oran-e2sim # this will create a folder called oran-e2sim
cd oran-e2sim/e2sim/
mkdir build
./build_e2sim.sh 3

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:

RUN mkdir /workspace/e2sim/e2sim/build
WORKDIR /workspace/e2sim/e2sim/build # Creation and cd on the build directory
RUN cmake .. -DDEV_PKG=1 -DLOG_LEVEL=${log_level_e2sim} # build of the project with the LOG_LEVEL desired

RUN make package # Creation of the package
RUN echo "Going to install e2sim-dev"
RUN dpkg --install ./e2sim-dev_1.0.0_amd64.deb # Installation of the generated package on the system
RUN ldconfig  # library update to make the package linkable from ns-3 without rebooting the machine

It is now time to clone and install the ns3-mmWave project:

git clone https://github.com/wineslab/ns-o-ran-ns3-mmwave ns-3-mmwave-oran
cd ns-3-mmwave-oran

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 contrib directory:

cd ns-3-mmwave-oran/contrib
git clone -b master https://github.com/o-ran-sc/sim-ns3-o-ran-e2 oran-interface
cd ..  # go back to the ns-3-mmwave-oran folder

We now have all the software in place to configure and build ns-3:

./waf configure --enable-examples --enable-tests
./waf build

Scenario Zero

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:

./waf --run scratch/scenario-zero.cc

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:

• E2 Setup Request (ns-O-RAN to E2 Term on RIC);
• E2 Setup Response (E2 Term on RIC to ns-O-RAN);
• E2 Subscription Request (xApp to ns-O-RAN through E2 Term on RIC);
• E2 Subscription Response (ns-O-RAN to xApp through E2 Term on RIC);
• E2SM RIC Indication Message (ns-O-RAN to xApp through E2 Term on 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:

A. Lacava, M. Polese, R. Sivaraj, R. Soundrarajan, B.S. Bhati, T. Singh, T. Zugno, F. Cuomo, and T. Melodia, "Programmable and Customized Intelligence for Traffic Steering in 5G Networks Using Open RAN Architectures," arXiv:2209.14171 [cs.NI], pp. 1-15, October 2022. [pdf] [bibtex]