5G OpenAirInterface with O-RAN near-RT RIC

How to setup and use OpenAirInterface with a near-RT RIC


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 gNB on Colosseum equipped with a standard compliant E2 agent for the E2AP component and custom Service Models based on protocol buffers, together with a Near-RT RIC and a sample xApp.

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.

xApp Components

Base xApp

This is a basic xapp (base-xapp in xapp-oai submodule) that subscribes to selected RAN parameters, receives periodic indications messages and sends control requests to update these parameters. The base xApp can communicate with the gNB by means of a RIC, or via direct socket communication.

xApp SM Connector

This component (xapp-sm-connector in xapp-oai submodule) connects the xApp with the RIC. In downstream (from the xApp to the gNB), the connector receives our custom sm buffers to be encapsulated in E2AP messages and sent to the RIC. In upstream (from the gNB to the xApp), the connector retrieves custom Service Model (SM) buffers from E2AP to be sent to the xApp.

RIC Components

See ColO-RAN for a detailed description of the RIC components.

Base Station Components


Similar to what the xApp SM Connector does, the E2SIM component (e2sim submodule) encapsulates/decapsulates custom SM buffers that are to be sent or that are received from the gNB. It communicates with the gNB via UDP sockets.

gNB Emulator

This component (in the e2protobuf submodule) is a simple gNB emulator to test custom SMs without running a real gNB.

Protobuf Definitions

This repository contains our custom protobuf definitions (in the oai-oran-protolib submodule).

OpenAirInterface with xApp Agent

This component (openairinterface5g submodule) is a fork of OpenAirInterface with the addition of a custom xApp agent.

Running the Base xApp with gNB Emulator

Start by making a reservation on Colosseum that includes oai-ric (the login credentials are root/pass). For the following steps, we recommend using a terminal multiplexer such as tmux or screen.

Start the gNB emulator. The emulated gNB is now waiting for incoming messages.


Start the RIC:


Check that the following containers are running by using the command docker ps


Start e2sim:

cd ocp-e2sim

If in the e2mgr logs you see something like the following, it means that e2sim has successfully registered with the RIC:

{"crit":"INFO","ts":1666880119183,"id":"E2Manager","msg":"#RmrSender.Send - RAN name: >gnb_734_733_b5c67780 , Message type: 12002 - Successfully sent RMR message","mdc":>>>>{"time":"2022-10-27 14:15:19.183"}}

Start the base xApp container:


Start the xApp SM Connector:

docker exec -it base-xapp-24 bash
cd ../xapp-oai/xapp-sm-connector/

Wait for the following lines to appear:

about to call xapp startup
Still waiting for indreq buf...
Opened control socket server on port 7000

The SM Connector is now ready to communicate with the base xApp. To run the xApp:

docker exec -it base-xapp-24 bash
cd ../xapp-oai/base-xapp/
python3 run_xapp.py

The base xApp will now receive periodic RIC Indication messages from the gNB. When an indication message is received, the xApp sends a control request to write the target RAN parameters with random data. This is how it normally looks like in the base xApp:

Received  14  bytes
Recevied RIC indication response:
param_map {
  key: GNB_ID
  value: "8"
param_map {
  value: "1"

Sending RIC indication control with random data
printing built control message:
msg_type: CONTROL
ran_control_request {
  target_param_map {
    key: GNB_ID
    value: "5"
  target_param_map {
    key: SOMETHING
    value: "3"

Socket sent 18 bytes

The gNB will show something similar to the following:

Received 8 bytes
ran message id 2
Indication request message received
Indication request for 2 parameters:
        Parameter id 1 requested (a.k.a gnb_id)
        Parameter id 2 requested (a.k.a something)
Sending indication response
Sent 14 bytes, buflen was 14

Received 18 bytes
ran message id 4
Control message received
Applying target parameter gnb_id with value 5
Applying target parameter something with value 3


Running the Base xApp with OAI gNB

This requires a Colosseum reservation with oai-ric and eugenio-ran-dev. The procedure is similar to the gNB emulator case, with the following differences:

Start the RIC in the SRN running with oai-ric:


Start the gNB in the SRN running with eugenio-ran-dev:

./run_gnb.sh -t donor

In the same SRN, also start the e2term:

cd ocp-e2sim