Colosseum Near-Real-Time RIC

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.

Structure

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

Quick start

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, where ric-network-interface is the interface from which you want to expose the RIC E2 termination (e.g., col0 or can0 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

setup-scripts directory

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 the coloran-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 here
setup-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., the col0 interface in Colosseum) is passed as argument. This script has been adapted from here
start-ric-arena.sh: script to start the near-real-time RIC on external testbeds, e.g., on the Arena platform
setup-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 papers
start-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

setup directory

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) container
e2: implementation of the E2 termination (e2term) container
e2mgr: implementation of the E2 manager (e2mgr) and of the routing manager simulator (e2rtmansim) container
sample-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.

Getting the gNB ID

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 is gnb: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"}

Using the provided sample xApp

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 the sample-xapp directory (which by defaults prints the data received from the RAN node) and the service model connector of the xapp-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.

kirlf/colosseum-near-rt-ric-docker-compose