A tutorial on how to deploy and extend the dApp framework, with a use case for spectrum sharing.
dApps are real-time microservices designed to operate within the O-RAN ecosystem, enabling sub-10 ms Artificial Intelligence (AI) routines in the Radio Access Network (RAN). This tutorial demonstrates how to set up and leverage our dApp framework with OpenAirInterface (OAI) to perform spectrum sharing. Additionally, we provide guidance on how this framework can be adapted to other use cases in 5G and beyond.
The dApp framework is designed for co-location with the CU/DU, where it can interact directly with user-plane data. The modularity of our framework ensures flexibility, allowing developers to tailor it to various spectrum-sharing scenarios or extend it for other AI-driven optimizations in network management. It features:
This tutorial outlines the setup process and discusses how to customize the framework for different applications.
We set up a repository that connects our OAI version and our dApp framework.
Prerequisites: Our version of OAI needs the libczmq-dev
library installed in addition to the rest of mandatory OAI requirements.
On Debian-based systems this can be done with sudo apt install libczmq-dev
.
--build-e3
flag to enable dApp support:
git clone https://github.com/wineslab/dApp-openairinterface5g openairinterface5g
cd openairinterface5g
source oaienv
cd ./cmake_targets/
./build_oai -I # Install dependencies (do it only once)
./build_oai -w USRP --ninja --gNB --build-e3
do_SRS
flag is set to 0. Example:
taskset -ca 0-45 ./nr-softmodem -O <CONFIG_FILE_PATH> --gNBs.[0].min_rxtxtime 6 --sa --usrp-tx-thread-config 1 -E --T_stdout 2 --gNBs.[0].do_SRS 0
Prerequisites: Make sure that python3
and hatch
are installed in your system.
pip3 install hatch
For more details on how to install hatch
please refer to the official website.
We will soon update a stable version of the dapp
package on the official python repositories, thus these steps are intended to be conducted only to test the example Spectrum Sharing dApp presented in this tutorial.
git clone https://github.com/wineslab/dApp-library dApp
cd dApp
hatch build
pip3 install dist/*.tar.gz
taskset -ca 46-47 python3 examples/spectrum_dapp.py --ota --control --link zmq --transport ipc --demo-gui --save-iqs
The options available for this example include:
--ota
: Enable OTA configuration or specify if running on Colosseum.--link
: Specify the link layer to be used (default: zmq
).--transport
: Specify the transport layer to be used (default: ipc
).--save-iqs
: Enable data collection mode to save I/Q samples for offline analysis.--control
: Enable PRB blocking for spectrum management.--energy-gui
: Enable the Energy GUI through X11.--iq-plotter-gui
: Enable the I/Q Plotter GUI through X11.--demo-gui
: Enable the Demo GUI website.--timed
: Run for 5 minutes and exits.The included tutorial demonstrates a dApp for spectrum sharing. The same setup can be used for several use cases including:
Moreover, our framework can be extended by changing the E3SM implemented to support different payloads for the Indication Messages and the control actions, unlocking additional use cases. For more information about the use cases that benefit from the usage of dApps, please refer to the O-RAN nGRG Research Report nGRG-RR-2024-10. The E3AP does not need any change and can be used as it is.
The framework presented in this tutorial is also available as a Linux container on Colosseum.
The name of the container is oai-dapp
with password dapps
.
To replicate this tutorial on Colosseum, create a reservation with at least four different nodes in the same order as presented here:
oai-5gcore-2024
: Core for OAI that allows the identification and pairing of the UE to the network. Password for this container is pass
.
A detailed tutorial that describes how the core and OAI work on Colosseum is present here;oai-dapp
: our container that will act as a gNB with a dApp embedded;oai-dapp
: our container that will act as a UE;cast
: container from [1], used on this case as an external incumbent. Password for this container is cast123
;Once the reservation has been deployed, start a Radio Frequency (RF) scenario on Colosseum, e.g., scenario 10011
(All Paths 0 dB, 3.6 GHz as center frequency, 10 nodes max).
colosseumcli rf start 10011 -c
Run the OAI 5G Core-network as indicated in the original tutorial:
cd oai-cn5g
docker compose up -d
Access the first oai-dapp
container, create a tmux
session and start the gNB operations with the aforementioned commands.
In the openairinterface5g
folder, we have also a utility script perform the commands automatically:
cd ~/openairinterface5g
./run_oai.sh
Please edit this file and the configuration according to your needs.
Split the tmux
session or open a new terminal and create a new window that will be dedicated to the dApp.
For Colosseum, we use a different noise floor threshold by not including the --ota
parameter.
cd ~/dApp
python3 examples/spectrum_dapp.py --control --link zmq --transport ipc --demo-gui
With the flag --demo-gui
, you should be able to access a webpage on your browser that shows the I/Q samples sensed by the gNB and delivered by to the dApp.
To make the dApp faster the taskset
utility can be used, please check the above command and the number of available cores on the SRN with nproc
.
Subsequently, access the second oai-dapp
container and start the UE operations, as shown in the original tutorial:
cd OAI-Colosseum
python3 ran.py -t ue -m sa
Since the sensed I/Qs are extracted from a reserved OFDM slot, the UE communication will not be shown in the web interface.
Finally, access the incumbent container (i.e., cast
) and start a uniform noise with the command:
uhd_siggen --freq 3.6288e9 --samp-rate 1e6 --gain 70 -m 1 --uniform
The expected output is that the dApp is able to detect the presence of a signal on the incumbent and block the PRBs affected.
While this tutorial focuses on spectrum sharing, the framework can be adapted to numerous other applications, making it a valuable resource for researchers and developers in the O-RAN ecosystem.
If you use this framework in your work, please cite our paper:
A. Lacava, L. Bonati, N. Mohamadi, R. Gangula, F. Kaltenberger, P. Johari, S. D’Oro, F. Cuomo, M. Polese, and T. Melodia, "dApps: Enabling Real-Time AI-Based Open RAN Control," arXiv:2501.16502 [cs.NI], pp. 1-31, January 2025. [pdf] [bibtex]