dApp Framework Tutorial: Deploy and Extend dApps

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:

  • Extensibility: Modular design of the classes that can be extended for custom use cases.
  • Adaptability: Works with diverse configurations, including over-the-air (OTA) and wireless testing platforms like Colosseum.
  • Real-Time Capabilities: Designed to meet the sub-10 ms latency requirements of O-RAN, with control loops periodicity below 1 μs.

This tutorial outlines the setup process and discusses how to customize the framework for different applications.

Framework Setup

We set up a repository that connects our OAI version and our dApp framework.

Setting Up the gNB

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.

  1. Clone and Build OAI: Clone the OAI repository and include the --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
    
  2. Launch OAI: Run OAI before starting the dApp, ensuring the 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
    

Setting Up the dApp

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.

  1. Clone the dApp repository
    git clone https://github.com/wineslab/dApp-library dApp
    cd dApp
    
  2. Build and install the Python package
     hatch build
     pip3 install dist/*.tar.gz
    
  3. Run the dApp
    Start the dApp with the following command:
    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.

Example Application: Spectrum Sharing

The included tutorial demonstrates a dApp for spectrum sharing. The same setup can be used for several use cases including:

  • Dynamic Spectrum Allocation: Implement algorithms to assign PRBs based on real-time traffic demands.
  • Spectrum Sensing: Analyze I/Q samples to detect and mitigate interference.

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.

Use dApps on Colosseum

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.

dApp dashboard normal

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.

dApp dashboard with incumbent

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]