From dd81e019be4d7773329bf0d30f034080482bbfca Mon Sep 17 00:00:00 2001 From: mychele Date: Thu, 9 Dec 2021 09:39:37 -0500 Subject: [PATCH] Update README --- README.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d97b88c..2f2ec51 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Colosseum Near-Real-Time RIC -This is a minimal implementation of the O-RAN Software Community near-real-time RIC (Bronze release) adapted and extended to work on the [Colosseum](https://www.colosseum.net/) 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`). -A sample xApp, which connects to the [SCOPE](https://github.com/wineslab/colosseum-scope) RAN environment through the following [E2 termination](https://github.com/wineslab/colosseum-scope-e2) is also provided. +This is a minimal version of the O-RAN Software Community near-real-time RIC (Bronze release) adapted and extended to work on the [Colosseum](https://www.colosseum.net/) wireless network emulator. +The scripts in this repository will start a minimal near-real-time RIC in the form of Docker containers (namely, `dbaas`, `e2mgr`, `e2rtmansim`, `e2term`). +The repository also features a sample xApp, which connects to the [SCOPE](https://github.com/wineslab/colosseum-scope) RAN environment through the following [E2 termination](https://github.com/wineslab/colosseum-scope-e2). If you use this software, please reference the following paper: @@ -44,6 +44,8 @@ root ### Quick start +We provide a Colosseum LXC container that contains this repository, its prerequisites, and base docker images. The container XXX can be found among the images available for Colosseum users. + From the `setup-scripts` directory: - Build, configure, and start the near-real-time RIC Docker containers: `./setup-ric.sh` - Connect the RAN node through the E2 termination as explained [here](https://github.com/wineslab/colosseum-scope-e2) @@ -55,19 +57,21 @@ From the `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 XXX 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](https://gitlab.flux.utah.edu/johnsond/ric-profile/-/blob/master/setup-lib.sh) -- `setup-ric.sh`: script to build, configure, and start the near-real-time RIC containers of this repository (namely, `db`, `e2mgr`, `e2rtmansim`, `e2term`). This script has been adapted from [here](https://gitlab.flux.utah.edu/johnsond/ric-profile/-/blob/master/setup-ric.sh) +- `setup-ric.sh`: script to build, configure, and start the near-real-time RIC containers of this repository (namely, `dbaas`, `e2mgr`, `e2rtmansim`, `e2term`). This script has been adapted from [here](https://gitlab.flux.utah.edu/johnsond/ric-profile/-/blob/master/setup-ric.sh) - `start-ric-arena.sh`: script to start the near-real-time RIC on external testbeds, e.g., on the [Arena platform](https://ece.northeastern.edu/wineslab/arena.php) -- `setup-sample-xapp.sh`: script to setup a sample xApp Docker container. This xApp is capable of connecting to the [SCOPE](https://github.com/wineslab/colosseum-scope) RAN environment through the following [E2 termination](https://github.com/wineslab/colosseum-scope-e2) -- `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 +- `setup-sample-xapp.sh`: script to setup a sample xApp Docker container. This xApp is capable of connecting to the [SCOPE](https://github.com/wineslab/colosseum-scope) RAN environment through the following [E2 termination](https://github.com/wineslab/colosseum-scope-e2). 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](https://ece.northeastern.edu/wineslab/papers/bonati2021intelligence.pdf) +- `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`](setup-scripts) directory. -- `dbaas`: implementation of a Redis database (`db`) container +- `dbaas`: implementation of a Redis database (`dbaas`) 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-bs-connector`: implementation of the sample xApp provided in this repository and components to connect to the near-real-time RIC and [SCOPE](https://github.com/wineslab/colosseum-scope) RAN environment +These components are adapted from the [O-RAN Software Community RIC platform (Bronze)](https://github.com/o-ran-sc), 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: @@ -85,5 +89,5 @@ An easy way to derive the gNB ID is the following. From the `setup-scripts` dire The sample xApp provided in this repository connects to the [SCOPE](https://github.com/wineslab/colosseum-scope) RAN environment through the following [E2 termination](https://github.com/wineslab/colosseum-scope-e2). 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` -- Move to the right directory inside the Docker container: `cd /home/sample-xapp` -- Start the xApp: `./run_xapp.sh`. This script will open a socket between the sample script in the `sample-xapp` directory (which by defaults prints the data received from the RAN node) and the base station connector of the `xapp-bs-connector` directory. Then, the xApp will subscribe to the RAN node specified at contianer startup time through the gNB ID, and send a RIC Indication Message that triggers a data report from the RAN node with the periodicity of 1 second. +- 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 base station connector of the `xapp-bs-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.