dapps 0.0.2__tar.gz → 0.0.4__tar.gz

{dapps-0.0.2 → dapps-0.0.4}/.github/workflows/tag-and-release.yml

@@ -9,7 +9,7 @@ jobs:
   create-tag:
     runs-on: ubuntu-latest
     outputs:
-      version: ${{ steps.set_version.outputs.version }}
+      version: ${{ steps.get_version.outputs.version }}
       tag_created: ${{ steps.set_output.outputs.tag_created }}
     steps:
       - name: Checkout repository
@@ -48,11 +48,6 @@ jobs:
             echo "tag_created=false" >> $GITHUB_OUTPUT
           fi
 
-      - name: Set version output
-        id: set_version
-        run: |
-          echo "version=${{ steps.get_version.outputs.version }}" >> $GITHUB_OUTPUT
-
   build:
     name: Build distribution 📦
     runs-on: ubuntu-latest
@@ -78,7 +73,9 @@ jobs:
 
   publish-to-pypi:
     name: Publish to PyPI
-    needs: build
+    needs: 
+      - build
+      - create-tag
     runs-on: ubuntu-latest
     if: ${{ needs.create-tag.outputs.tag_created == 'true' && github.repository == 'wineslab/dApp-library' }}
     environment:
@@ -97,7 +94,9 @@ jobs:
 
   github-release:
     name: Sign packages with Sigstore and upload them to GitHub Release
-    needs: publish-to-pypi
+    needs: 
+      - publish-to-pypi
+      - create-tag
     runs-on: ubuntu-latest
     if: ${{ needs.create-tag.outputs.tag_created == 'true' && github.repository == 'wineslab/dApp-library' }}
     permissions:
@@ -126,7 +125,9 @@ jobs:
 
   publish-to-testpypi:
     name: Publish to TestPyPI
-    needs: build
+    needs: 
+      - publish-to-pypi
+      - create-tag
     runs-on: ubuntu-latest
     if: ${{ needs.create-tag.outputs.tag_created == 'true' && github.repository == 'wineslab/dApp-library' }}
     environment:

dapps-0.0.4/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: dapps
+Version: 0.0.4
+Summary: A library for creating and connecting dApps to Open RAN units.
+Project-URL: Homepage, https://openrangym.com/o-ran-frameworks/dapps
+Project-URL: Package, https://pypi.org/project/dapps/
+Project-URL: Source, https://github.com/wineslab/dApp-library
+Project-URL: Bug Tracker, https://github.com/wineslab/dApp-library/issues
+Author-email: Andrea Lacava <thecave003@gmail.com>
+License-File: LICENSE
+Keywords: 5G,O-RAN,cellular,dApps,networks
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+Requires-Dist: asn1tools
+Requires-Dist: numpy
+Requires-Dist: pyzmq
+Requires-Dist: typing-extensions
+Provides-Extra: all
+Requires-Dist: flask; extra == 'all'
+Requires-Dist: flask-socketio; extra == 'all'
+Requires-Dist: influxdb-client; extra == 'all'
+Requires-Dist: libiq; extra == 'all'
+Requires-Dist: matplotlib; extra == 'all'
+Requires-Dist: pysctp; extra == 'all'
+Provides-Extra: api
+Requires-Dist: influxdb-client; extra == 'api'
+Provides-Extra: cnn
+Requires-Dist: libiq; extra == 'cnn'
+Provides-Extra: gui
+Requires-Dist: flask; extra == 'gui'
+Requires-Dist: flask-socketio; extra == 'gui'
+Requires-Dist: matplotlib; extra == 'gui'
+Provides-Extra: network
+Requires-Dist: pysctp; extra == 'network'
+Description-Content-Type: text/markdown
+
+# dApp Library
+
+A complete tutorial on how to deploy a dApp can be found on the [OpenRAN Gym website](https://openrangym.com/tutorials/dapps-oai). Please refer to that guide to instrument your system.
+
+## Installation
+
+### Python package installation (recommended)
+
+```
+pip3 install dapps[all]
+```
+
+The dApp can be found in the `examples` directory or it can be downloaded from this repository.
+
+### Manual installation (use only for library development)
+
+Clone the repository and install it manually with:
+
+```
+hatch build
+pip3 install dist/*.tar.gz
+```
+
+### Launch the Spectrum Sharing dApp example
+
+OAI should start _before_ running the dApp
+
+```python 
+python3 examples/spectrum_dapp.py
+```
+
+This dApp implements a spectrum sharing use case discussed in [our paper](https://doi.org/10.1016/j.comnet.2025.111342) ([here for the archive version](https://arxiv.org/pdf/2501.16502)).
+The dApp parameters can be controlled through the following command-line arguments:
+
+- `--link` (str, default: 'zmq', choices: [layer.value for layer in E3LinkLayer]): Specify the link layer to be used  
+- `--transport` (str, default: 'ipc', choices: [layer.value for layer in E3TransportLayer]): Specify the transport layer to be used  
+- `--save-iqs` (store_true, default: False): Specify if this is data collection run or not. In the first case I/Q samples will be saved  
+- `--control` (store_true, default: False): Set whether to perform control of PRB  
+- `--noise-floor-threshold` (int, default: None): Set the noise floor threshold for determining the presence of incumbents and for detecting the PRBs affected.
+- `--ota` (store_true, default: False): Specify if the setup used is OTA or on Colosseum for determining the noise floor threshold. If the `noise_floor_threshold` parameter is specified, this parameter is ignored
+- `--energy-gui` (store_true, default: False): Set whether to enable the energy GUI  
+- `--iq-plotter-gui` (store_true, default: False): Set whether to enable the IQ Plotter GUI  
+- `--demo-gui` (store_true, default: False): Set whether to enable the Demo GUI  
+- `--num-prbs` (int, default: 106): Number of PRBs  
+- `--num-subcarrier-spacing` (int, default: 30): Subcarrier spacing in kHz (FR1 is 30)  
+- `--e` (store_true, default: False): Set if 3/4 sampling for FFT size is set on the gNB (-E option on OAI)  
+- `--center-freq` (float, default: 3.6192e9): Center frequency in Hz  
+- `--timed` (store_true, default: False): Run with a 5-minute time limit  
+- `--model` (str, default: ''): Path to the CNN model file to be used  
+- `--time-window` (int, default: 5): Number of input vectors to pass to the CNN model  
+- `--moving-avg-window` (int, default: 30): Window size (in samples) for the moving average used to detect energy peaks in the spectrum  
+- `--extraction-window` (int, default: 600): Number of samples to retain after detecting an energy peak
+
+
+If you use the dApp concept and/or the framework to develop your own dApps, please cite the following paper:
+
+```text
+@article{LACAVA2025111342,
+title = {{dApps: Enabling Real-Time AI-based Open RAN Control}},
+journal = {Computer Networks},
+pages = {111342},
+year = {2025},
+issn = {1389-1286},
+doi = {https://doi.org/10.1016/j.comnet.2025.111342},
+url = {https://www.sciencedirect.com/science/article/pii/S1389128625003093},
+author = {Andrea Lacava and Leonardo Bonati and Niloofar Mohamadi and Rajeev Gangula and Florian Kaltenberger and Pedram Johari and Salvatore D’Oro and Francesca Cuomo and Michele Polese and Tommaso Melodia},
+keywords = {Open RAN, dApps, Real-time control loops, Radio Resource Management (RRM), Spectrum sharing, Positioning, Integrated Sensing and Communication (ISAC)},
+abstract = {Open Radio Access Networks (RANs) leverage disaggregated and programmable RAN functions and open interfaces to enable closed-loop, data-driven radio resource management. This is performed through custom intelligent applications on the RAN Intelligent Controllers (RICs), optimizing RAN policy scheduling, network slicing, user session management, and medium access control, among others. In this context, we have proposed dApps as a key extension of the O-RAN architecture into the real-time and user-plane domains. Deployed directly on RAN nodes, dApps access data otherwise unavailable to RICs due to privacy or timing constraints, enabling the execution of control actions within shorter time intervals. In this paper, we propose for the first time a reference architecture for dApps, defining their life cycle from deployment by the Service Management and Orchestration (SMO) to real-time control loop interactions with the RAN nodes where they are hosted. We introduce a new dApp interface, E3, along with an Application Protocol (AP) that supports structured message exchanges and extensible communication for various service models. By bridging E3 with the existing O-RAN E2 interface, we enable dApps, xApps, and rApps to coexist and coordinate. These applications can then collaborate on complex use cases and employ hierarchical control to resolve shared resource conflicts. Finally, we present and open-source a dApp framework based on OpenAirInterface (OAI). We benchmark its performance in two real-time control use cases, i.e., spectrum sharing and positioning in a 5th generation (5G) Next Generation Node Base (gNB) scenario. Our experimental results show that standardized real-time control loops via dApps are feasible, achieving average control latency below 450microseconds and allowing optimal use of shared spectral resources.}
+}
+```

dapps-0.0.4/README.md

@@ -0,0 +1,70 @@
+# dApp Library
+
+A complete tutorial on how to deploy a dApp can be found on the [OpenRAN Gym website](https://openrangym.com/tutorials/dapps-oai). Please refer to that guide to instrument your system.
+
+## Installation
+
+### Python package installation (recommended)
+
+```
+pip3 install dapps[all]
+```
+
+The dApp can be found in the `examples` directory or it can be downloaded from this repository.
+
+### Manual installation (use only for library development)
+
+Clone the repository and install it manually with:
+
+```
+hatch build
+pip3 install dist/*.tar.gz
+```
+
+### Launch the Spectrum Sharing dApp example
+
+OAI should start _before_ running the dApp
+
+```python 
+python3 examples/spectrum_dapp.py
+```
+
+This dApp implements a spectrum sharing use case discussed in [our paper](https://doi.org/10.1016/j.comnet.2025.111342) ([here for the archive version](https://arxiv.org/pdf/2501.16502)).
+The dApp parameters can be controlled through the following command-line arguments:
+
+- `--link` (str, default: 'zmq', choices: [layer.value for layer in E3LinkLayer]): Specify the link layer to be used  
+- `--transport` (str, default: 'ipc', choices: [layer.value for layer in E3TransportLayer]): Specify the transport layer to be used  
+- `--save-iqs` (store_true, default: False): Specify if this is data collection run or not. In the first case I/Q samples will be saved  
+- `--control` (store_true, default: False): Set whether to perform control of PRB  
+- `--noise-floor-threshold` (int, default: None): Set the noise floor threshold for determining the presence of incumbents and for detecting the PRBs affected.
+- `--ota` (store_true, default: False): Specify if the setup used is OTA or on Colosseum for determining the noise floor threshold. If the `noise_floor_threshold` parameter is specified, this parameter is ignored
+- `--energy-gui` (store_true, default: False): Set whether to enable the energy GUI  
+- `--iq-plotter-gui` (store_true, default: False): Set whether to enable the IQ Plotter GUI  
+- `--demo-gui` (store_true, default: False): Set whether to enable the Demo GUI  
+- `--num-prbs` (int, default: 106): Number of PRBs  
+- `--num-subcarrier-spacing` (int, default: 30): Subcarrier spacing in kHz (FR1 is 30)  
+- `--e` (store_true, default: False): Set if 3/4 sampling for FFT size is set on the gNB (-E option on OAI)  
+- `--center-freq` (float, default: 3.6192e9): Center frequency in Hz  
+- `--timed` (store_true, default: False): Run with a 5-minute time limit  
+- `--model` (str, default: ''): Path to the CNN model file to be used  
+- `--time-window` (int, default: 5): Number of input vectors to pass to the CNN model  
+- `--moving-avg-window` (int, default: 30): Window size (in samples) for the moving average used to detect energy peaks in the spectrum  
+- `--extraction-window` (int, default: 600): Number of samples to retain after detecting an energy peak
+
+
+If you use the dApp concept and/or the framework to develop your own dApps, please cite the following paper:
+
+```text
+@article{LACAVA2025111342,
+title = {{dApps: Enabling Real-Time AI-based Open RAN Control}},
+journal = {Computer Networks},
+pages = {111342},
+year = {2025},
+issn = {1389-1286},
+doi = {https://doi.org/10.1016/j.comnet.2025.111342},
+url = {https://www.sciencedirect.com/science/article/pii/S1389128625003093},
+author = {Andrea Lacava and Leonardo Bonati and Niloofar Mohamadi and Rajeev Gangula and Florian Kaltenberger and Pedram Johari and Salvatore D’Oro and Francesca Cuomo and Michele Polese and Tommaso Melodia},
+keywords = {Open RAN, dApps, Real-time control loops, Radio Resource Management (RRM), Spectrum sharing, Positioning, Integrated Sensing and Communication (ISAC)},
+abstract = {Open Radio Access Networks (RANs) leverage disaggregated and programmable RAN functions and open interfaces to enable closed-loop, data-driven radio resource management. This is performed through custom intelligent applications on the RAN Intelligent Controllers (RICs), optimizing RAN policy scheduling, network slicing, user session management, and medium access control, among others. In this context, we have proposed dApps as a key extension of the O-RAN architecture into the real-time and user-plane domains. Deployed directly on RAN nodes, dApps access data otherwise unavailable to RICs due to privacy or timing constraints, enabling the execution of control actions within shorter time intervals. In this paper, we propose for the first time a reference architecture for dApps, defining their life cycle from deployment by the Service Management and Orchestration (SMO) to real-time control loop interactions with the RAN nodes where they are hosted. We introduce a new dApp interface, E3, along with an Application Protocol (AP) that supports structured message exchanges and extensible communication for various service models. By bridging E3 with the existing O-RAN E2 interface, we enable dApps, xApps, and rApps to coexist and coordinate. These applications can then collaborate on complex use cases and employ hierarchical control to resolve shared resource conflicts. Finally, we present and open-source a dApp framework based on OpenAirInterface (OAI). We benchmark its performance in two real-time control use cases, i.e., spectrum sharing and positioning in a 5th generation (5G) Next Generation Node Base (gNB) scenario. Our experimental results show that standardized real-time control loops via dApps are feasible, achieving average control latency below 450microseconds and allowing optimal use of shared spectral resources.}
+}
+```

dapps-0.0.4/VERSION

@@ -0,0 +1 @@
+0.0.4

dapps-0.0.4/examples/spectrum_dapp.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Example script to showcase the Spectrum Sharing dApp 
+"""
+
+import argparse
+import multiprocessing
+import os
+import time
+
+from e3interface.e3_connector import E3LinkLayer, E3TransportLayer
+from spectrum.spectrum_dapp import SpectrumSharingDApp
+
+LOG_DIR = ('.' if os.geteuid() != 0 else '') + '/logs/'
+
+def stop_program(time_to_wait, dapp: SpectrumSharingDApp):
+    time.sleep(time_to_wait)
+    print("Stop is called")
+    dapp.stop()
+    time.sleep(0.5) # to allow proper closure of the dApp threads, irrelevant to profiling
+    print("Test completed")
+
+def main(args, time_to_wait: float = 60.0):
+    # with open(f"{LOG_DIR}/busy.txt", "w") as f:
+    #     f.close()
+
+    if args.model:
+        try:
+            from libiq.classifier.cnn import Classifier
+        except ModuleNotFoundError:
+            print(
+                "Optional dependencies to run this example are not installed.\n"
+                "Fix this by running:\n\n"
+                "    pip install libiq  # OR\n"
+                "    pip install dapps[cnn] (minimal) # OR\n"
+                "    pip install dapps[all] (preferred)\n"
+            )
+            exit(-1)
+
+    # This value really depends on the RF conditions and the RU used and should be carefully calibrated
+    if args.noise_floor_threshold:
+        print(f'Using custom configuration')
+        noise_floor_threshold = args.noise_floor_threshold
+    else:    
+        if args.ota:
+            print(f'Using OTA configuration')
+            noise_floor_threshold = 20 
+        else: # Colosseum
+            print(f'Using Colosseum configuration')
+            noise_floor_threshold = 53
+
+    print(f'Threshold is {noise_floor_threshold}')
+
+    classifier = None
+    if args.model:
+        import math
+        ofdm_symbol_size = args.num_prbs * 12  # 12 subcarriers per PRB always fixed by LTE/NR standard
+        fft_size = 2 ** math.ceil(math.log2(ofdm_symbol_size))  # Next power of 2
+        classifier = Classifier(
+            time_window = args.time_window,
+            input_vector = fft_size,
+            moving_avg_window = args.moving_avg_window,
+            extraction_window = args.extraction_window,
+            model_path = args.model
+        )
+
+    dapp = SpectrumSharingDApp(noise_floor_threshold=noise_floor_threshold, save_iqs=args.save_iqs, control=args.control, link=args.link, transport=args.transport,
+                energyGui=args.energy_gui, iqPlotterGui=args.iq_plotter_gui, dashboard=args.demo_gui, classifier=classifier, center_freq=args.center_freq,
+                num_prbs=args.num_prbs, e_sampling=args.e, num_subcarrier_spacing= args.num_subcarrier_spacing)
+
+    dapp.setup_connection()
+    
+    if args.timed:
+        timer = multiprocessing.Process(target=stop_program, args=(time_to_wait, dapp))
+        timer.start()
+    else:
+        timer = None
+
+    try:
+        dapp.control_loop()
+    finally:
+        if args.timed:
+            timer.kill()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Example of a dApp for Spectrum Sharing")
+    parser.add_argument('--link', type=str, default='zmq', choices=[layer.value for layer in E3LinkLayer], help="Specify the link layer to be used")
+    parser.add_argument('--transport', type=str, default='ipc', choices=[layer.value for layer in E3TransportLayer], help="Specify the transport layer to be used")
+    parser.add_argument('--save-iqs', action='store_true', default=False, help="Specify if this is data collection run or not. In the first case I/Q samples will be saved")
+    parser.add_argument('--control', action='store_true', default=False, help="Set whether to perform control of PRB")
+    parser.add_argument('--noise-floor-threshold', type=int, default=None, help="Set the noise floor threshold for determining the presence of incumbents and for detecting the PRBs affected.")
+    parser.add_argument('--ota', action='store_true', default=False, help="Specify if the setup used is OTA or on Colosseum for determining the noise floor threshold. If the `noise_floor_threshold` parameter is specified, this parameter is ignored")
+    parser.add_argument('--energy-gui', action='store_true', default=False, help="Set whether to enable the energy GUI")
+    parser.add_argument('--iq-plotter-gui', action='store_true', default=False, help="Set whether to enable the IQ Plotter GUI")
+    parser.add_argument('--demo-gui', action='store_true', default=False, help="Set whether to enable the Demo GUI")
+    parser.add_argument('--num-prbs', type=int, default=106, help="Number of PRBs")
+    parser.add_argument('--num-subcarrier-spacing', type=int, default=30, help="Subcarrier spacing in kHz (FR1 is 30)")
+    parser.add_argument('--e', action='store_true', default=False, help="Set if 3/4 sampling for FFT size is set on the gNB (-E option on OAI)")
+    parser.add_argument('--center-freq', type=float, default=3.6192e9, help="Center frequency in Hz")
+    parser.add_argument('--timed', action='store_true', default=False, help="Run with a 5-minute time limit")
+    parser.add_argument('--model', type=str, default='', help="Path to the CNN model file to be used")
+    parser.add_argument('--time-window', type=int, default=5, help="Number of input vectors to pass to the CNN model.")
+    parser.add_argument('--moving-avg-window', type=int, default=30, help="Window size (in samples) for the moving average used to detect energy peaks in the spectrum.")
+    parser.add_argument('--extraction-window', type=int, default=600, help="Number of samples to retain after detecting an energy peak.")
+
+    args = parser.parse_args()
+    print("Start dApp")
+
+    main(args)

dapps-0.0.4/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = [ "hatchling" ]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "dapps"
+dynamic = [ "version" ]
+description = "A library for creating and connecting dApps to Open RAN units."
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = [ "dApps", "O-RAN", "5G", "cellular", "networks" ]
+classifiers = [
+"Development Status :: 4 - Beta",
+"Programming Language :: Python",
+"Programming Language :: Python :: 3.8",
+"Programming Language :: Python :: 3.9",
+"Programming Language :: Python :: 3.10",
+"Programming Language :: Python :: 3.11",
+"Programming Language :: Python :: 3.12",
+"Programming Language :: Python :: Implementation :: CPython",
+"Programming Language :: Python :: Implementation :: PyPy"
+]
+dependencies = [ "asn1tools", "typing_extensions", "numpy", "pyzmq" ]
+
+
+[[project.authors]]
+name = "Andrea Lacava"
+email = "thecave003@gmail.com"
+
+
+[project.urls]
+Homepage = "https://openrangym.com/o-ran-frameworks/dapps"
+Package = "https://pypi.org/project/dapps/"
+Source = "https://github.com/wineslab/dApp-library"
+"Bug Tracker" = "https://github.com/wineslab/dApp-library/issues"
+
+
+[project.optional-dependencies]
+api = [ "influxdb_client" ]
+cnn = [ "libiq" ]
+gui = [ "flask", "flask-socketio", "matplotlib" ]
+network = [ "pysctp" ]
+all = [
+"pysctp",
+"flask",
+"flask-socketio",
+"matplotlib",
+"influxdb_client",
+"libiq"
+]
+
+
+[tool.hatch.version]
+path = "VERSION"
+pattern = "(?P<version>\\d+\\.\\d+\\.\\d+)"
+
+
+[tool.hatch.build.targets.wheel]
+packages = [
+"src/dapp",
+"src/e3interface",
+"src/spectrum",
+"src/visualization"
+]
+sources = [ "src" ]

{dapps-0.0.2 → dapps-0.0.4}/src/dapp/dapp.py

@@ -19,7 +19,7 @@ LOG_DIR = ('.' if os.geteuid() != 0 else '') + '/logs/'
 class DApp(ABC):
     e3_interface: E3Interface
 
-    def __init__(self, id: int = 1, link: str = 'posix', transport:str = 'uds', callbacks: list = [], **kwargs):
+    def __init__(self, id: int = 1, link: str = 'posix', transport:str = 'ipc', callbacks: list = [], **kwargs):
         super().__init__()
         self.dapp_id = id
         self.e3_interface = E3Interface(link=link, transport=transport)

{dapps-0.0.2 → dapps-0.0.4}/src/e3interface/defs/e3.asn

@@ -10,7 +10,7 @@ E3 DEFINITIONS AUTOMATIC TAGS ::= BEGIN
     }
 
     E3-IndicationMessage ::= SEQUENCE {
-        protocolData          OCTET STRING (SIZE(1..8192))
+        protocolData          OCTET STRING (SIZE(1..16384))
     }
 
     E3-ControlAction ::= SEQUENCE {

{dapps-0.0.2 → dapps-0.0.4}/src/spectrum/spectrum_dapp.py

@@ -15,26 +15,36 @@ from e3interface.e3_logging import dapp_logger, LOG_DIR
 
 class SpectrumSharingDApp(DApp):
 
-    ###  Configuration ###
-    # gNB runs with BW = 40 MHz, with -E (3/4 sampling)
+    ###  Default Configuration ###
+    # gNB runs with BW = ~40 MHz
     # Center frequency = 3.6192 GHz
-    # OAI sampling frequency 46.08e6
+    # OAI sampling frequency 46.08e6 # not useful for visualization
     # No SRS for now, hence in gNB config file set do_SRS = 0
-    # gNB->frame_parms.ofdm_symbol_size = 1536
-    # gNB->frame_parms.first_carrier_offset = 900
-    # Noise floor threshold needs to be calibrated
-    # We receive the symbols and average them over some frames, and do thresholding.
-
-    def __init__(self, id: int = 1, noise_floor_threshold: int = 53, save_iqs: bool = False, control: bool = False, link: str = 'posix', transport:str = 'uds', **kwargs):
-        super().__init__(link=link, transport=transport, **kwargs) 
-
-        self.bw = 40.08e6  # Bandwidth in Hz
-        self.center_freq = 3.6192e9 # Center frequency in Hz
-        self.First_carrier_offset = 900
-        self.Num_car_prb = 12
-        self.prb_thrs = 75 # This avoids blacklisting PRBs where the BWP is scheduled (it’s a workaround bc the UE and gNB would not be able to communicate anymore, a cleaner fix is to move the BWP if needed or things like that)
-        self.FFT_SIZE = 1536  
-        self.Average_over_frames = 63
+    # gNB->frame_parms.ofdm_symbol_size = 1536 # FFT size (even though is called ofdm_symbol_size) for USRP, with -E flag (3/4 sampling)
+    # gNB->frame_parms.ofdm_symbol_size = 2048 # FFT size (even though is called ofdm_symbol_size) for RUs, with no -E flag
+    # Noise floor threshold needs to be calibrated according to the RU
+    # We receive the symbols, average them over 63 frames and do PRB thresholding.
+
+    def __init__(self, id: int = 1, link: str = 'posix', transport: str = 'ipc', noise_floor_threshold: int = 53, save_iqs: bool = False, control: bool = False,
+                center_freq: float = 3.6192e9, num_prbs: int = 106, num_subcarrier_spacing: int = 30, e_sampling: bool = False, **kwargs):
+        super().__init__(id=id, link=link, transport=transport, **kwargs) 
+
+        # gNB radio configuration used to compute exact values
+        self.num_consecutive_subcarriers_for_prb: int = 12 # Always fixed by the LTE/NR standard to 12
+        self.num_prbs = num_prbs
+        self.num_subcarrier_spacing = num_subcarrier_spacing # subcarrier spacing in kHz (FR1 is 30)
+        self.ofdm_symbol_size = num_prbs * self.num_consecutive_subcarriers_for_prb
+        self.bw = self.num_prbs * self.num_consecutive_subcarriers_for_prb * self.num_subcarrier_spacing * 1e3 # Bandwidth in Hz
+        self.center_freq = center_freq # Center frequency in Hz
+        self.fft_size = 2 ** int(np.ceil(np.log2(self.ofdm_symbol_size))) # Next power of 2 to include guard bands
+        if e_sampling:
+            self.fft_size = int(self.fft_size * 3 / 4) # 3/4 of sampling for USRPs (-E flag) 
+        self.first_carrier_offset = self.fft_size - (self.ofdm_symbol_size // 2)
+
+        # dApp configuration
+        # The first 76 PRB usually have channels that should not be nulled (but we should investigate more options to enable this)
+        self.prb_thrs = 75 # This avoids blacklisting PRBs where the BWP is scheduled (it’s a workaround since the UE and gNB would not be able to communicate anymore, a cleaner fix is to move the BWP if needed or things like that)  
+        self.average_over_frames = 63
         self.noise_floor_threshold = noise_floor_threshold
         self.save_iqs = save_iqs
         self.e3_interface.add_callback(self.get_iqs_from_ran)
@@ -50,25 +60,24 @@ class SpectrumSharingDApp(DApp):
         self.dashboard = kwargs.get('dashboard', False)
 
         self.control_count = 1
-        self.abs_iq_av = np.zeros(self.FFT_SIZE)
+        self.abs_iq_av = np.zeros(self.fft_size)
 
         if self.energyGui:
             from visualization.energy import EnergyPlotter
             self.sig_queue = multiprocessing.Queue() 
-            self.energyPlotter = EnergyPlotter(self.FFT_SIZE, bw=self.bw, center_freq=self.center_freq) 
+            self.energyPlotter = EnergyPlotter(self.fft_size, bw=self.bw, center_freq=self.center_freq) 
 
         if self.iqPlotterGui:
             from visualization.iq import IQPlotter
             self.iq_queue = multiprocessing.Queue() 
-            iq_size = self.FFT_SIZE * 2 # double the size of ofdm_symbol_size since real and imaginary parts are interleaved
-            self.iqPlotter = IQPlotter(buffer_size=500, iq_size=iq_size, bw=self.bw, center_freq=self.center_freq)    
+            self.iqPlotter = IQPlotter(buffer_size=500, fft_size=self.fft_size, bw=self.bw, center_freq=self.center_freq)    
 
         if self.dashboard:
             from visualization.dashboard import Dashboard
             self.demo_queue = multiprocessing.Queue()
-            iq_size = self.FFT_SIZE * 2 # double the size of ofdm_symbol_size since real and imaginary parts are interleaved
             classifier = kwargs.get('classifier', None)
-            self.demo = Dashboard(buffer_size=100, iq_size=iq_size, classifier=classifier) 
+            self.demo = Dashboard(buffer_size=100, ofdm_symbol_size=self.ofdm_symbol_size, first_carrier_offset=self.first_carrier_offset,
+                                bw=self.bw, center_freq=self.center_freq, num_prbs=num_prbs, classifier=classifier) 
 
     def get_iqs_from_ran(self, data):
         dapp_logger.debug(f'Triggered callback')
@@ -83,7 +92,7 @@ class SpectrumSharingDApp(DApp):
                
         iq_arr = np.frombuffer(data, dtype=np.int16)
         dapp_logger.debug(f"Shape of iq_arr {iq_arr.shape}")
-        
+
         if self.iqPlotterGui:
             self.iq_queue.put(iq_arr)
 
@@ -100,9 +109,9 @@ class SpectrumSharingDApp(DApp):
             self.control_count += 1
             dapp_logger.debug(f"Control count is: {self.control_count}")
 
-            if self.control_count == self.Average_over_frames:
-                abs_iq_av_db =  20 * np.log10(1 + (self.abs_iq_av/(self.Average_over_frames)))
-                abs_iq_av_db_offset_correct = np.append(abs_iq_av_db[self.First_carrier_offset:self.FFT_SIZE],abs_iq_av_db[0:self.First_carrier_offset])
+            if self.control_count == self.average_over_frames:
+                abs_iq_av_db =  20 * np.log10(1 + (self.abs_iq_av/(self.average_over_frames)))
+                abs_iq_av_db_offset_correct = np.append(abs_iq_av_db[self.first_carrier_offset:self.fft_size],abs_iq_av_db[0:self.first_carrier_offset])
                 dapp_logger.info(f'--- AVG VALUES ----')
                 dapp_logger.info(f'abs_iq_av_db_offset_correct: {abs_iq_av_db_offset_correct.mean()}')
                 dapp_logger.info(f'--- MAX VALUES ----')
@@ -111,11 +120,11 @@ class SpectrumSharingDApp(DApp):
                 # dapp_logger.info(f'Last 20 max values (abs_iq_av_db_offset_correct): {last_5_max_abs_iq_av_db_offset_correct}')
 
                 # PRB blocking based on the noise floor threshold
-                f_ind = np.arange(self.FFT_SIZE)
+                f_ind = np.arange(self.fft_size)
                 blklist_sub_carrier = f_ind[abs_iq_av_db_offset_correct > self.noise_floor_threshold]
                 np.sort(blklist_sub_carrier)
                 dapp_logger.info(f'blklist_sub_carrier: {blklist_sub_carrier}')
-                prb_blk_list = np.unique((np.floor(blklist_sub_carrier/self.Num_car_prb))).astype(np.uint16)
+                prb_blk_list = np.unique((np.floor(blklist_sub_carrier/self.num_consecutive_subcarriers_for_prb))).astype(np.uint16)
                 dapp_logger.info(f'prb_blk_list: {prb_blk_list}')
                 prb_blk_list = prb_blk_list[prb_blk_list > self.prb_thrs]
                 # prb_blk_list = np.array([76, 77,  78,  79, 80, 81, 82, 83], dtype=np.uint16) # 76, 77,  78,  79, 80, 81, 82, 83
@@ -137,7 +146,7 @@ class SpectrumSharingDApp(DApp):
                     self.demo_queue.put(("prb_list", prb_blk_list))
 
                 # Reset the variables
-                self.abs_iq_av = np.zeros(self.FFT_SIZE)
+                self.abs_iq_av = np.zeros(self.fft_size)
                 self.control_count = 1  
 
     def _control_loop(self):

{dapps-0.0.2 → dapps-0.0.4}/src/visualization/dashboard.py

@@ -14,18 +14,21 @@ except ModuleNotFoundError:
 import numpy as np
 
 class Dashboard:
-    def __init__(self, buffer_size=100, iq_size=1536, bw=46.08e6, center_freq=3.6192e9, classifier=None):
-        # TODO double check killing conditions
+    # The default values of the dashboard are based on the default configuration
+    def __init__(self, buffer_size: int = 100, ofdm_symbol_size: int = 1272, bw: float = 38.16e6, center_freq: float = 3.6192e9, 
+                 num_prbs: int = 106, first_carrier_offset: int = 900, classifier = None):
         # Flask app setup
         self.app = Flask(__name__)
         self.app.config['TEMPLATES_AUTO_RELOAD'] = True
         self.socketio = SocketIO(self.app)
 
         # Parameters
-        self.BUFFER_SIZE = buffer_size
-        self.iq_size = iq_size
-        self.BW = bw
-        self.CENTER_FREQ = center_freq
+        self.buffer_size = buffer_size
+        self.ofdm_symbol_size = ofdm_symbol_size
+        self.bw = bw
+        self.center_freq = center_freq
+        self.num_prbs = num_prbs
+        self.first_carrier_offset = first_carrier_offset
         
         # Route setup
         self.app.add_url_rule("/", view_func=self.index)
@@ -51,20 +54,12 @@ class Dashboard:
         self.run_thread.start()
 
     def handle_initial_connection(self):
-        num_prbs = 106
-        iqs_to_show = int(
-            self.iq_size / 2
-        )  # / 2 since the size received is real and imaginary part
-        # Each PRB corresponds to 12 subcarriers
-        # Parameter first_carrier_offset (currently set to 900) is the first subcarrier.
-        # So PRB 0 is [900-911], 1 is [912-923], etc. They wrap around fft_size (now at 1536)
-        # The carrier frequency is in the middle PRB (including DC leak on some radios), this means it falls at (first_carrier_offset + 106*12/2) % fft_size? where % is the modulo operation
-        # The first 76 PRB usually have channels that should not be nulled (but we should investigate more options to enable this)
-        # So if you want the spectrum waterfall to correspond to the PRB masking plot, you can rotate them as per bullet 2 above and drop [635-899]
-        iqs_to_show -= 264  # is the size of the array to drop
         data_buffer = {
-            "magnitude": np.zeros((self.BUFFER_SIZE, iqs_to_show)).tolist(),
-            "num_prbs": num_prbs,
+            "magnitude": np.zeros((self.buffer_size, self.ofdm_symbol_size)).tolist(),
+            "center_freq": self.center_freq,
+            "bw": self.bw,
+            "num_prbs": self.num_prbs,
+            "first_carrier_offset": self.first_carrier_offset,
             "predicted_label": self.classifier is not None
         }
         self.socketio.emit("initialize_plot", data_buffer)
@@ -84,8 +79,6 @@ class Dashboard:
         plot, payload = message
         if plot == "iq_data":
             iq_data = payload
-            if iq_data.size != self.iq_size:
-                raise ValueError(f'Expected IQ data of size {self.iq_size}, but got {iq_data.size}')
 
             self.sampling_counter += 1        
             if self.sampling_counter >= self.sampling_threshold:
@@ -105,7 +98,6 @@ class Dashboard:
     def stop(self):
         """Stops the server and kills the thread."""
         if self.run_thread and self.run_thread.is_alive():
-            self.socketio.stop()
             self.run_thread.join()
 
 if __name__ == "__main__":