This is a part of the OpenRAN Gym project. It is minimal version of the O-RAN Software Community near-real-time RIC (Bronze release) adapted and extended to work on the Colosseum wireless network emulator.
The scripts in this repository will start a minimal near-real-time RIC in the form of Docker containers (namely, db
, e2mgr
, e2rtmansim
, e2term
).
The repository also features a sample xApp, which connects to the SCOPE RAN environment through the following E2 termination.
If you use this software, please reference the following paper:
M. Polese, L. Bonati, S. D'Oro, S. Basagni, T. Melodia, "ColoRAN: Design and Testing of Open RAN Intelligence on Large-scale Experimental Platforms," arXiv 2112.09559 [cs.NI], December 2021. bibtex pdf
This work was partially supported by the U.S. National Science Foundation under Grants CNS-1923789 and NSF CNS-1925601, and the U.S. Office of Naval Research under Grant N00014-20-1-2132.
This repository is organized as follows
/root/radio_code/colosseum-near-rt-ric
|
└──setup-scripts
| |
| └──import-base-images.sh
| |
| └──setup-lib.sh
| |
| └──setup-ric.sh
| |
| └──setup-sample-xapp.sh
| |
| └──start-ric-arena.sh
| |
| └──start-xapp.sh
|
└──setup
| |
| └──dbaas
| |
| └──e2
| |
| └──sample-xapp
| |
| └──xapp-sm-connector
We provide a Colosseum LXC container that contains this repository, its prerequisites, and base docker images. The container coloran-near-rt-ric-prebuilt
can be found among the images available for Colosseum users. The default username and password are root
and ChangeMe
.
From the setup-scripts
directory:
- Build, configure, and start the near-real-time RIC Docker containers:
./setup-ric.sh ric-network-interface
, whereric-network-interface
is the interface from which you want to expose the RIC E2 termination (e.g.,col0
orcan0
in Colosseum). - Connect the RAN node through the E2 termination as explained here
- Get the gNB ID (see section below) and replace it in the
start-xapp.sh
script - Configure and start the xApp:
./start-xapp.sh
The setup-scripts
directory contains scripts to initialize the near-real-time RIC on Colosseum.
import-base-images.sh
: script to import the base Docker images needed to build the RIC Docker containers. These images are provided as part of thecoloran-near-rt-ric
Colosseum LXC container.setup-lib.sh
: contains the IP addresses and ports used by the Docker containers of this repository. This script has been adapted from heresetup-ric.sh
: script to build, configure, and start the near-real-time RIC containers of this repository (namely,db
,e2mgr
,e2rtmansim
,e2term
). The network interface the RIC listens to for connections (e.g., thecol0
interface in Colosseum) is passed as argument. This script has been adapted from herestart-ric-arena.sh
: script to start the near-real-time RIC on external testbeds, e.g., on the Arena platformsetup-sample-xapp.sh
: script to setup a sample xApp Docker container. This xApp is capable of connecting to the SCOPE RAN environment through the following E2 termination. Custom or standard-compliant service models can be implemented on top of the RAN E2 termination and the sample xApp, as done for example in these papersstart-xapp.sh
: script to configure and start the sample xApp. The ID of the gNB targeted by the xApp needs to be provided in the script, as discussed below
This directory contains the implementations of the near-real-time RIC Docker container initialized through the scripts in the setup-scripts
directory.
dbaas
: implementation of a Redis database (db
) containere2
: implementation of the E2 termination (e2term
) containere2mgr
: implementation of the E2 manager (e2mgr
) and of the routing manager simulator (e2rtmansim
) containersample-xapp
,xapp-sm-connector
: implementation of the sample xApp provided in this repository and components to connect to the near-real-time RIC and SCOPE RAN environment
These components are adapted from the O-RAN Software Community RIC platform (Bronze), which we extended to support the Colosseum environment, concurrent connections from multiple base stations and xApps, and to provide improved support for encoding, decoding and routing of control messages.
An easy way to derive the gNB ID is the following. From the setup-scripts
directory:
-
Start the near-real-time RIC Docker containers:
./setup-ric.sh
-
Read the logs of the
e2term
container:docker logs e2term -f
-
Connect the RAN node through the E2 termination as explained here
-
The RAN node should connect to the near-real-time RIC and the gNB ID should appear in the
e2term
logs. In the example below, the gNB ID isgnb:311-048-01000501
{"ts":1639008174427,"crit":"DEBUG","id":"E2Terminator","mdc":{"thread id":"139898725332736"},"msg":"After processing message and sent to rmr for : gnb:311-048-01000501, Read time is : 0 seconds, 1044889 nanoseconds"}
The sample xApp provided in this repository connects to the SCOPE RAN environment through the following E2 termination. After the near-real-time RIC has successfully started, the DU connected to it, and the xApp has been properly configured and started (see "Quick start" section above):
- Enter the xApp docker container (named
sample-xapp-24
by default):docker exec -it sample-xapp-24 bash
- Move to the
/home/sample-xapp
directory inside the Docker container:cd /home/sample-xapp
- Run the xApp logic:
./run_xapp.sh
. This script will open a socket between the sample Python script in thesample-xapp
directory (which by defaults prints the data received from the RAN node) and the service model connector of thexapp-sm-connector
directory, which performs ASN.1 encoding and decoding of E2AP messages. Then, the xApp will subscribe to the RAN node specified at container startup time through the gNB ID, and receive a RIC Indication Message with a data report from the RAN node with the periodicity of 250 ms.