OpenAirInterface (OAI) is a 3GPP-compliant software implementation of the full 5G NR stack. In this tutorial, we show how OpenRAN Gym users can get started with deploying an OAI 5G NR SA network composed of a gNB and a few UEs on Colosseum. Additionally, this tutorial shows how to deploy a nRT-RIC and an xApp developed to manage Guaranteed Bit Rate (GBR) Service Level Agreements (SLAs) of the RAN UEs.

More details in this paper:

E. Moro, M. Polese, A. Capone, T. Melodia, "An Open RAN Framework for the Dynamic Control of 5G Service Level Agreements," in Proceedings of IEEE NFV-SDN, Dresden, Germany, November 2023. [pdf] [bibtex]

Please consider citing the paper above if you use the O-RAN-compliant OAI gNB, the xApp SDK and the custom E2SM definitions in your research.

The basic repository for this project can be found here. It contains submodules that point to the different projects that are relevant to this tutorial.

Prerequisites

Please make a Colosseum reservation with the following images (credentials are root/pass for all):

• oai-core-gbr for the core network
• oai-ran-gbr for both the gNB and the UEs (at least 3 UEs are suggested)
• nrt-ric-gbr for the nRT-RIC and the xApp

Deployment and testing

Once the reservation is ready, start the core network in the oai-core SRN:

./start_core.sh

Then start the near-RT RIC in the oai-ric SRN:

start-ric.sh

and take note of the IP address of the SRN:

ifconfig col0 | grep 'inet addr:' | cut -d: -f2 | awk '{ print $1}'

You can check if all the ric components are running by using the command docker ps, whose result should be this:

e2term:ricindi
e2mgr:latest
e2rtmansim:latest
dbaas:latest
xapp:latest

Start the gNB in the oai-ran-gbr SRN:

./run_gnb.sh -t donor

In the same SRN, start the e2term:

./run_e2sim.sh RIC_IP RIC_PORT

where RIC_IP is the col0 IP address you have previously found, and RIC_PORT is the default 36422. The E2 Agent of the gNB is successfully connected with the RIC if the following line is shown:

[E2AP] Received SETUP-RESPONSE-SUCCESS

Before connecting the reserved UEs to the gNB, start the following Colosseum RF scenario:

colosseumcli rf start -c 10011

Now connect all the UEs by running the following in the UE containers:

./run_ue.sh

We now start the xApp. Back to the RIC container, attach a terminal to the xApp docker container:

docker exec -it xapp bash

Different SLA management xApps are available, please refer to the paper above for all the details. We start the advanced xApp implementing an elastic SLA policy:

python3 elastic_sla.py

Finally, we can generate downlink UE traffic as follows. In every UE container, add the route to the core network host:

ip route add 192.168.70.128/26 via 12.1.1.1

and take note of the UE GPRS Tunneling Protocol (GTP) endpoint IP:

ifconfig oaitun_ue1 | grep 'inet addr:' | cut -d: -f2 | awk '{ print $1}'

Run an iperf3 server in the UE SRN:

iperf3 -s

and test the connection in downlink by running this in the oai-core SRN:

docker exec -it oai-spgwu iperf3 -c UE_IP 

where UE_IP is the UE GTP endpoint IP.