dapps 0.0.7__tar.gz → 0.0.8__tar.gz

{dapps-0.0.7 → dapps-0.0.8}/.github/workflows/mirror.yml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
       with:
         fetch-depth: '0'  # Ensures the entire history is fetched
 

{dapps-0.0.7 → dapps-0.0.8}/.github/workflows/tag-and-release.yml

@@ -13,7 +13,7 @@ jobs:
       tag_created: ${{ steps.set_output.outputs.tag_created }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0  # Ensure we fetch all tags
 
@@ -54,11 +54,11 @@ jobs:
     needs: create-tag
     if: ${{ needs.create-tag.outputs.tag_created == 'true' && github.repository == 'wineslab/dApp-library' }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.8"
       - name: Install pypa/build

dapps-0.0.8/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Run tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    if: github.repository != 'wineslab/dApp-library'
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install hatch
+        run: pip install hatch
+
+      - name: Run tests
+        run: hatch run pytest tests/ -v

dapps-0.0.8/CONTRIBUTORS

@@ -0,0 +1,44 @@
+# Author
+
+- Andrea Lacava <thecave003@gmail.com>
+  - Initial dApp framework design and implementation
+  - E3 ASN.1 protocol definitions and encoder
+  - E3 connection setup and JSON/E3AP dual encoding
+  - Structured E3SM for multi-use-case support
+  - Spectrum Sharing dApp and IQ saver with SigMF compliance
+  - IQ saver file rotation
+  - Dashboard GUI and visualization
+  - Multi-PRB and multi-frequency support
+  - PyPI packaging and release workflow
+
+
+# Contributors
+
+Listed in chronological order of first contribution.
+We are grateful for every contribution, big or small, that helped shape this project.
+
+- Leonardo Bonati <38320780+leonardobonati@users.noreply.github.com>
+  - Debug print cleanup and comments
+
+- Michele Polese <michele.polese@gmail.com>
+  - README improvements and paper reference
+
+- Filippo Olimpieri <126257005+Ninjabippo1205@users.noreply.github.com>
+  - Spectrum Classification dApp via libiq integration
+  - E2SM-dApp report message and xApp control action
+  - dAppReport generation for the Spectrum SM
+  - Scheduler control support
+
+- Chris Wozny <woznych@gmail.com>
+  - Adaptive noise floor logic
+  - DC leakage filtering in PRB blacklist computation
+  - Visualization fixes
+
+- Antonio Scarvaglieri <20925479+absentio@users.noreply.github.com>
+  - dApp deregistration and RAN function unsubscribe
+  - Graceful shutdown and timed execution improvements
+
+- Ayush Patel <ayushnpatel22@gmail.com>
+  - Ground truth labeling system for IQ dataset collection
+  - Dashboard GUI improvements (display rate, waterfall threshold, label selector)
+  - SigMF annotation enhancements

{dapps-0.0.7 → dapps-0.0.8}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: dapps
-Version: 0.0.7
+Version: 0.0.8
 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>, Filippo Olimpieri <filippo.olimpieri@gmail.com>, Chris Wozny <woznych@gmail.com>
+Author-email: Andrea Lacava <thecave003@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: 5G,O-RAN,cellular,dApps,networks
@@ -77,43 +77,54 @@ This dApp implements a spectrum sharing use case discussed in [our paper](https:
 **Command-line arguments:**
 
 **Connection Configuration:**
+
 - `--link` - Specify the link layer to be used. Options: `zmq`, `posix` (default: `zmq`)
 - `--transport` - Specify the transport layer to be used. Options: `ipc`, `tcp` (default: `ipc`)
 
 **Data Collection and Control:**
+
 - `--save-iqs` - Enable data collection mode. When set, I/Q samples will be saved to disk for later analysis using SigMF
 - `--control` - Enable PRB control. When set, the dApp will actively control spectrum allocation based on detected interference. If not set, the dApp can still receive and implement control action from an external xApp
 
 **Spectrum Sensing Configuration:**
+
 - `--noise-floor-threshold` - Set the noise floor threshold (in dB) for determining the presence of incumbents and for detecting the PRBs affected. If not specified, will be auto-detected based on environment
 - `--ota` - Specify if the setup is Over-The-Air (OTA) or on Colosseum testbed for using a precalculated noise floor threshold. If `--noise-floor-threshold` is specified, this parameter is ignored
 
 **Visualization Options:**
+
 - `--energy-gui` - Enable the energy spectrum visualization GUI
 - `--iq-plotter-gui` - Enable the I/Q constellation plotter GUI
 - `--demo-gui` - Enable the demonstration GUI showing real-time spectrum occupancy
+- `--show-controls` - Show tunable controls (sampling threshold) in the dashboard GUI. Only meaningful with `--demo-gui`
+- `--ground-truth LABEL` - Initial ground truth label written into IQ annotations (only used with `--save-iqs`). Updatable at runtime via the dashboard GUI when `--demo-gui` is also set. When no PRBs are detected the label is forced to `no_rfi` regardless of what is set
 
 **Radio Configuration:**
+
 - `--num-prbs` - Number of Physical Resource Blocks in the channel (default: 106)
 - `--num-subcarrier-spacing` - Subcarrier spacing in kHz. Use 30 for FR1 (sub-6 GHz) (default: 30)
 - `--e` - Enable 3/4 FFT sampling mode. Set this flag if the gNB was started with the `-E` option
 - `--center-freq` - Center frequency in Hz (default: 3.6192e9, which is 3.6192 GHz)
 
 **Execution Control:**
+
 - `--timed SECONDS` - Run the dApp with a time limit (in seconds). Set to 0 for no limit (default: 0)
 
 **AI/ML Model Configuration:**
+
 - `--model` - Path to a pre-trained CNN model file for spectrum classification. If not provided, uses rule-based detection
 - `--time-window` - Number of consecutive spectrum vectors to use as input for the CNN model (default: 5)
 
 **Signal Processing Parameters:**
+
 - `--moving-avg-window` - Window size (in samples) for the moving average filter used to smooth energy measurements and detect peaks in the spectrum (default: 30)
 - `--extraction-window` - Number of samples to retain after detecting an energy peak for further analysis (default: 600)
-- `--sampling-threshold` - Down-sampling ratio applied to IQ sensing. An IQ vector will be delivered every Nth sensing (default: 5)
+- `--sampling-threshold` - Controls dashboard visualization rate: a new frame is rendered every N IQ batches (default: 5). Has no effect on IQ delivery from the gNB or on IQ recording to disk. Tunable at runtime via the dashboard when `--show-controls` is active
 
 **Adaptive Noise Floor Parameters:**
+
 - `--use-adaptive-noise-floor` - Enable adaptive noise floor thresholding using a per-bin median magnitude computed over a rolling history buffer, instead of a fixed noise floor threshold (default: False)
-- `--adaptive-hist-depth` - Number of IQ observation frames to retain in the adaptive noise floor circular buffer. A noise floor estimate will not be produced until this many frames have been collected (default: 32)
+- `--average_over_frames - Number of IQ observation frames to retain in the adaptive noise floor circular buffer. A noise floor estimate will not be produced until this many frames have been collected (default: 32)
 - `--noise-floor-threshold` - When using adaptive noise floor, the minimum SNR in dB that a bin must exceed to be considered a detection. When not using adaptive noise floor, the fixed magnitude threshold in dB above which a bin is considered active (default: 53)
 - `--embargo-timeout-secs` - Minimum time in seconds a PRB remains blocked after its last detection, regardless of the current SNR. Should be set to 1-2x the longest expected detection period to handle infrequent waveforms (default: 9.9)
 

{dapps-0.0.7 → dapps-0.0.8}/README.md

@@ -34,43 +34,54 @@ This dApp implements a spectrum sharing use case discussed in [our paper](https:
 **Command-line arguments:**
 
 **Connection Configuration:**
+
 - `--link` - Specify the link layer to be used. Options: `zmq`, `posix` (default: `zmq`)
 - `--transport` - Specify the transport layer to be used. Options: `ipc`, `tcp` (default: `ipc`)
 
 **Data Collection and Control:**
+
 - `--save-iqs` - Enable data collection mode. When set, I/Q samples will be saved to disk for later analysis using SigMF
 - `--control` - Enable PRB control. When set, the dApp will actively control spectrum allocation based on detected interference. If not set, the dApp can still receive and implement control action from an external xApp
 
 **Spectrum Sensing Configuration:**
+
 - `--noise-floor-threshold` - Set the noise floor threshold (in dB) for determining the presence of incumbents and for detecting the PRBs affected. If not specified, will be auto-detected based on environment
 - `--ota` - Specify if the setup is Over-The-Air (OTA) or on Colosseum testbed for using a precalculated noise floor threshold. If `--noise-floor-threshold` is specified, this parameter is ignored
 
 **Visualization Options:**
+
 - `--energy-gui` - Enable the energy spectrum visualization GUI
 - `--iq-plotter-gui` - Enable the I/Q constellation plotter GUI
 - `--demo-gui` - Enable the demonstration GUI showing real-time spectrum occupancy
+- `--show-controls` - Show tunable controls (sampling threshold) in the dashboard GUI. Only meaningful with `--demo-gui`
+- `--ground-truth LABEL` - Initial ground truth label written into IQ annotations (only used with `--save-iqs`). Updatable at runtime via the dashboard GUI when `--demo-gui` is also set. When no PRBs are detected the label is forced to `no_rfi` regardless of what is set
 
 **Radio Configuration:**
+
 - `--num-prbs` - Number of Physical Resource Blocks in the channel (default: 106)
 - `--num-subcarrier-spacing` - Subcarrier spacing in kHz. Use 30 for FR1 (sub-6 GHz) (default: 30)
 - `--e` - Enable 3/4 FFT sampling mode. Set this flag if the gNB was started with the `-E` option
 - `--center-freq` - Center frequency in Hz (default: 3.6192e9, which is 3.6192 GHz)
 
 **Execution Control:**
+
 - `--timed SECONDS` - Run the dApp with a time limit (in seconds). Set to 0 for no limit (default: 0)
 
 **AI/ML Model Configuration:**
+
 - `--model` - Path to a pre-trained CNN model file for spectrum classification. If not provided, uses rule-based detection
 - `--time-window` - Number of consecutive spectrum vectors to use as input for the CNN model (default: 5)
 
 **Signal Processing Parameters:**
+
 - `--moving-avg-window` - Window size (in samples) for the moving average filter used to smooth energy measurements and detect peaks in the spectrum (default: 30)
 - `--extraction-window` - Number of samples to retain after detecting an energy peak for further analysis (default: 600)
-- `--sampling-threshold` - Down-sampling ratio applied to IQ sensing. An IQ vector will be delivered every Nth sensing (default: 5)
+- `--sampling-threshold` - Controls dashboard visualization rate: a new frame is rendered every N IQ batches (default: 5). Has no effect on IQ delivery from the gNB or on IQ recording to disk. Tunable at runtime via the dashboard when `--show-controls` is active
 
 **Adaptive Noise Floor Parameters:**
+
 - `--use-adaptive-noise-floor` - Enable adaptive noise floor thresholding using a per-bin median magnitude computed over a rolling history buffer, instead of a fixed noise floor threshold (default: False)
-- `--adaptive-hist-depth` - Number of IQ observation frames to retain in the adaptive noise floor circular buffer. A noise floor estimate will not be produced until this many frames have been collected (default: 32)
+- `--average_over_frames - Number of IQ observation frames to retain in the adaptive noise floor circular buffer. A noise floor estimate will not be produced until this many frames have been collected (default: 32)
 - `--noise-floor-threshold` - When using adaptive noise floor, the minimum SNR in dB that a bin must exceed to be considered a detection. When not using adaptive noise floor, the fixed magnitude threshold in dB above which a bin is considered active (default: 53)
 - `--embargo-timeout-secs` - Minimum time in seconds a PRB remains blocked after its last detection, regardless of the current SNR. Should be set to 1-2x the longest expected detection period to handle infrequent waveforms (default: 9.9)
 

dapps-0.0.8/VERSION

@@ -0,0 +1 @@
+0.0.8

{dapps-0.0.7 → dapps-0.0.8}/examples/spectrum_dapp.py

@@ -106,6 +106,8 @@ def main(args):
         e_sampling=args.e,
         num_subcarrier_spacing=args.num_subcarrier_spacing,
         sampling_threshold=args.sampling_threshold,
+        ground_truth=args.ground_truth,
+        show_controls=args.show_controls,
         dapp_name="SpectrumSharing",
         dapp_version="1.0.0",
         vendor="WinesLab",
@@ -202,7 +204,15 @@ if __name__ == "__main__":
     parser.add_argument('--extraction-window', type=int, default=600,
                         help="Samples to retain after CNN energy peak detection")
     parser.add_argument('--sampling-threshold', type=int, default=5,
-                        help="Deliver IQ every N sensing cycles (each cycle is 10 ms)")
+                        help="Render a new dashboard frame every N IQ batches (visualization only, does not affect IQ delivery or recording)")
+    parser.add_argument('--ground-truth', type=str, default='', metavar='LABEL',
+                        help="Initial ground truth label written into IQ annotations "
+                             "(only used with --save-iqs). "
+                             "Updatable at runtime via the dashboard GUI "
+                             "when --demo-gui is also set.")
+    parser.add_argument('--show-controls', action='store_true', default=False,
+                        help="Show tunable controls (sampling threshold) in the dashboard GUI. "
+                             "Only meaningful with --demo-gui.")
 
     args = parser.parse_args()
     print("Start dApp")

{dapps-0.0.7 → dapps-0.0.8}/pyproject.toml

@@ -25,8 +25,6 @@ dependencies = [ "asn1tools", "typing_extensions", "numpy", "pyzmq", "sigmf", "j
 
 authors = [
     {name = "Andrea Lacava", email = "thecave003@gmail.com"},
-    {name = "Filippo Olimpieri", email = "filippo.olimpieri@gmail.com"},
-    {name = "Chris Wozny", email = "woznych@gmail.com"}
 ]
 
 
@@ -52,6 +50,10 @@ all = [
 ]
 
 
+[tool.hatch.envs.default]
+features = ["gui", "api", "network"]
+dependencies = ["pytest"]
+
 [tool.hatch.version]
 path = "VERSION"
 pattern = "(?P<version>\\d+\\.\\d+\\.\\d+)"

{dapps-0.0.7 → dapps-0.0.8}/src/iq_saver/iq_saver.py

@@ -39,10 +39,11 @@ class IQSaver:
                  dtype: str = "ci16_le",
                  filename: str = None,
                  max_samples_per_file: Optional[int] = None,
+                 rotation_interval: Optional[float] = None,
                  **metadata_kwargs):
         """
         Initialize IQSaver with SigMF-compliant recording configuration.
-        
+
         Args:
             base_path: Directory for recordings (default: current directory)
             center_freq: Center frequency in Hz
@@ -56,6 +57,8 @@ class IQSaver:
             filename: Custom filename (without extension). If None, timestamp-based name is used
             max_samples_per_file: Maximum number of frames (save_samples calls) per file
                 before rotating to a new file. None disables rotation (single file).
+            rotation_interval: Time in seconds before rotating to a new file. None disables
+                time-based rotation. Can be combined with max_samples_per_file.
             **metadata_kwargs: Additional global metadata fields (stored under spear: namespace)
         """
         self.base_path = Path(base_path) if base_path else Path.cwd()
@@ -97,6 +100,10 @@ class IQSaver:
         self.max_samples_per_file = max_samples_per_file
         if max_samples_per_file is not None and max_samples_per_file <= 0:
             raise ValueError("max_samples_per_file must be positive.")
+        self.rotation_interval = rotation_interval
+        if rotation_interval is not None and rotation_interval <= 0:
+            raise ValueError("rotation_interval must be positive.")
+        self._file_start_time: Optional[float] = None
         
         self._session_timestamp_ms: Optional[int] = None
         self._file_index: int = 0
@@ -171,8 +178,9 @@ class IQSaver:
         
         # Write initial metadata file immediately (SigMF requires .sigmf-meta alongside .sigmf-data)
         # This ensures the file exists even if the program is interrupted
-        self._sigmf.tofile(str(self.base_path / base_filename))
-        
+        self._sigmf.tofile(str(self.base_path / base_filename), overwrite=True)
+
+        self._file_start_time = timestamp
         self._is_initialized = True
     
     def _rotate_file(self, timestamp: float) -> None:
@@ -183,7 +191,7 @@ class IQSaver:
             self._file_handle.close()
             self._file_handle = None
         if self._sigmf is not None and self._filename is not None:
-            self._sigmf.tofile(str(self.base_path / self._filename))
+            self._sigmf.tofile(str(self.base_path / self._filename), overwrite=True)
             self._all_files.append(self._filename)
 
         # Reset all state for new file
@@ -195,6 +203,7 @@ class IQSaver:
         self._is_initialized = False
         self._annotation_buffer.clear()
         self._annotation_count = 0
+        self._file_start_time = None
         self._file_index += 1
 
     def _finalize_file(self) -> None:
@@ -208,7 +217,7 @@ class IQSaver:
             self._flush_annotations()
             
             # Write final metadata file
-            self._sigmf.tofile(str(self.base_path / self._filename))
+            self._sigmf.tofile(str(self.base_path / self._filename), overwrite=True)
         
     def _get_iso8601_timestamp(self, timestamp: Optional[float] = None) -> str:
         """Convert Unix timestamp to ISO 8601 format for SigMF with microsecond precision."""
@@ -232,9 +241,13 @@ class IQSaver:
         if timestamp is None:
             timestamp = time.time()
         
-        # Check rotation condition (frame count threshold)
+        # Check rotation conditions (frame count or elapsed time)
         if self.max_samples_per_file is not None and self._sample_count >= self.max_samples_per_file:
             self._rotate_file(timestamp)
+        elif (self.rotation_interval is not None
+              and self._file_start_time is not None
+              and (timestamp - self._file_start_time) >= self.rotation_interval):
+            self._rotate_file(timestamp)
         
         # Initialize file on first write or after rotation
         if not self._is_initialized:
@@ -387,7 +400,7 @@ class IQSaver:
         
         # Write metadata file to disk after flushing annotations
         if self._sigmf is not None and self._filename is not None:
-            self._sigmf.tofile(str(self.base_path / self._filename))
+            self._sigmf.tofile(str(self.base_path / self._filename), overwrite=True)
     
     def update_sample_rate(self, new_sample_rate: float, sampling_threshold: int = None) -> None:
         """
@@ -432,6 +445,31 @@ class IQSaver:
         # Add new capture segment at current IQ sample position
         self._sigmf.add_capture(self._iq_sample_count, metadata=capture_metadata)
     
+    def add_waveform_description(self, timestamp: Optional[float] = None, **kwargs) -> bool:
+        """
+        Add a post-collection waveform description annotation (e.g. from an LLM or external classifier).
+        All kwargs are stored as custom spear: fields at the same sample index as the timestamp.
+        """
+        return self.add_annotation(timestamp=timestamp, label="waveform_description", **kwargs)
+
+    def get_recording_info(self) -> Dict[str, Any]:
+        """Return a snapshot of the current recording session state."""
+        all_files = list(self._all_files)
+        if self._filename:
+            all_files.append(self._filename)
+
+        file_paths = [str(self.base_path / f"{name}.sigmf-data") for name in all_files]
+        file_sizes = {p: Path(p).stat().st_size if Path(p).exists() else 0 for p in file_paths}
+
+        return {
+            "total_samples": self._iq_sample_count,
+            "total_files": len(all_files),
+            "pending_annotations": len(self._annotation_buffer),
+            "duration_seconds": time.time() - self._session_start_time,
+            "file_paths": file_paths,
+            "file_size_bytes": file_sizes,
+        }
+
     def close(self) -> None:
         """
         Finalize recording and write all metadata.

{dapps-0.0.7 → dapps-0.0.8}/src/spectrum/spectrum_dapp.py

@@ -163,6 +163,9 @@ class SpectrumSharingDApp(DApp):
         self.energyGui = kwargs.get('energyGui', False)
         self.iqPlotterGui = kwargs.get('iqPlotterGui', False)
         self.dashboard = kwargs.get('dashboard', False)
+        if self.save_iqs:
+            self._ground_truth_label = kwargs.get('ground_truth', "")
+            self._ground_truth_lock = threading.Lock()
 
         # Thread-safe sample_idx for IQ saver annotation cross-reference
         self._sample_idx_lock = threading.Lock()
@@ -195,6 +198,9 @@ class SpectrumSharingDApp(DApp):
                 classifier=classifier,
                 adaptiveThreshold=isinstance(self._detector, AdaptiveThresholdDetector),
                 control=self.control,
+                label_callback=self.set_ground_truth_label if self.save_iqs else None,
+                initial_label=self._ground_truth_label if self.save_iqs else "",
+                show_controls=kwargs.get('show_controls', False),
             )
 
     def _init_spectrum_encoder(self):
@@ -266,6 +272,13 @@ class SpectrumSharingDApp(DApp):
         self._sampling_threshold_control_callback = callback
         dapp_logger.info(f"Custom control logic callback {'set' if callback else 'removed'}")
 
+    def set_ground_truth_label(self, label: str):
+        with self._ground_truth_lock:
+            self._ground_truth_label = label
+        dapp_logger.info(f"Ground truth label set to: {label!r}")
+        if self.dashboard:
+            self.demo.emit_label(label)
+
     def create_prb_blacklist_control(self, blacklisted_prbs: list[int],
                                      update_sampling: bool = False,
                                      validity_period: int = None) -> bytes:
@@ -487,6 +500,9 @@ class SpectrumSharingDApp(DApp):
         dapp_logger.info(f"Sending Control to RAN: blockedPRBs={prb_blk_list}")
 
         if self.save_iqs:
+            if hasattr(self, '_ground_truth_label'):
+                with self._ground_truth_lock:
+                    ground_truth_label = self._ground_truth_label
             with self._sample_idx_lock:
                 if self.sample_idx is not None:
                     self.iq_saver.add_annotation(
@@ -498,6 +514,7 @@ class SpectrumSharingDApp(DApp):
                         noise_threshold=self._detector.threshold_db,
                         control_action="blacklist",
                         detector=type(self._detector).__name__,
+                        **({"ground_truth_label": ground_truth_label} if hasattr(self, '_ground_truth_label') else {}),
                     )
                     dapp_logger.info("Annotation added")
 
@@ -647,6 +664,10 @@ class SpectrumSharingDApp(DApp):
                 f"noise_floor_per_prb={ann.get('noise_floor_per_prb')} | "
                 f"snr_db_per_prb={ann.get('snr_db_per_prb')}"
             )
+            if hasattr(self, '_ground_truth_label'):
+                with self._ground_truth_lock:
+                    gt = self._ground_truth_label if detected_prbs.size > 0 else "no_rfi"
+                ann["ground_truth_label"] = gt
             with self._sample_idx_lock:
                 if self.sample_idx is not None:
                     self.iq_saver.add_annotation(start_sample=self.sample_idx, **ann)

{dapps-0.0.7 → dapps-0.0.8}/src/visualization/dashboard.py

@@ -3,21 +3,22 @@ try:
     from flask import Flask, render_template
     from flask_socketio import SocketIO
 except ModuleNotFoundError:
-                    print(
-                        "Optional dependencies for GUI not installed.\n"
-                        "Fix this by running:\n\n"
-                        "    pip install 'dApps[gui]'  # OR\n"
-                        "    pip install 'dApps[all]'\n",
-                        exc_info=True
-                    )
-                    exit(-1)
+    print(
+        "Optional dependencies for GUI not installed.\n"
+        "Fix this by running:\n\n"
+        "    pip install 'dApps[gui]'  # OR\n"
+        "    pip install 'dApps[all]'\n"
+    )
+    exit(-1)
 import numpy as np
 
 class Dashboard:
     # 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, prb_protected_below: int = 75,
-                 classifier=None, adaptiveThreshold=False, control: bool = False):
+                 classifier=None, adaptiveThreshold=False, control: bool = False,
+                 label_callback=None, initial_label: str = "", port: int = 7778,
+                 show_controls: bool = False):
         # Flask app setup
         self.app = Flask(__name__)
         self.app.config['TEMPLATES_AUTO_RELOAD'] = True
@@ -40,12 +41,22 @@ class Dashboard:
 
         self.classifier = classifier if classifier is not None else None
         self.adaptiveThreshold = adaptiveThreshold
+        self.label_callback = label_callback
+        self.current_label = initial_label
+        self.port = port
+        self.show_controls = show_controls
 
         # SocketIO event handlers
         self.socketio.on_event("connect", self.handle_initial_connection)
+        if self.label_callback is not None:
+            def _on_set_ground_truth_label(label):
+                self.current_label = label
+                self.label_callback(label)
+            self.socketio.on_event("set_ground_truth_label", _on_set_ground_truth_label)
+        self.socketio.on_event("set_sampling_threshold", self._on_set_sampling_threshold)
         self._initialize_plot()
 
-        # We do not show every iqs otherwise the GUI is too slow
+        # Render a new dashboard frame every N IQ batches — does not affect IQ delivery or recording
         self.sampling_counter = 0
         self.sampling_threshold = 5
 
@@ -53,7 +64,8 @@ class Dashboard:
         return render_template("index.html")
 
     def run(self):
-        self.socketio.run(self.app, host="0.0.0.0", port=7778, debug=False, use_reloader=False)
+        self.socketio.run(self.app, host="0.0.0.0", port=self.port, debug=False,
+                          use_reloader=False, allow_unsafe_werkzeug=True)
 
     def _initialize_plot(self):
         self.run_thread = threading.Thread(target=self.run, daemon=True)
@@ -76,9 +88,28 @@ class Dashboard:
             "prb_protected_below": self.prb_protected_below if self.control else None,
             "predicted_label": self.classifier is not None,
             "adaptive_noise_floor": self.adaptiveThreshold,
+            "show_label_selector": self.label_callback is not None,
+            "current_label": self.current_label,
+            "show_controls": self.show_controls,
+            "sampling_threshold": self.sampling_threshold,
         }
         self.socketio.emit("initialize_plot", data_buffer)
 
+    def emit_label(self, label: str):
+        self.current_label = label
+        self.socketio.emit("update_ground_truth_label", label)
+
+    def _on_set_sampling_threshold(self, value):
+        try:
+            rate = int(value)
+        except (TypeError, ValueError):
+            return
+        if rate < 1:
+            return
+        self.sampling_threshold = rate
+        self.socketio.emit("update_sampling_threshold", rate)
+        self.socketio.emit("reset_waterfall")
+
     def _process_iq_data(self, iq_data):
         real_part = iq_data[0::2]  # Even indices: real part
         imag_part = iq_data[1::2]  # Odd indices: imaginary part
@@ -96,7 +127,7 @@ class Dashboard:
         if plot == "iq_data":
             iq_data = payload
 
-            self.sampling_counter += 1        
+            self.sampling_counter += 1
             if self.sampling_counter >= self.sampling_threshold:
                 magnitude_dB = self._process_iq_data(iq_data)[::-1].tolist() # visualization processing is delegated to client
                 self.socketio.emit("update_plot", {"magnitude": magnitude_dB})
@@ -123,4 +154,32 @@ class Dashboard:
             self.run_thread.join(timeout=1)
 
 if __name__ == "__main__":
-    server_app = Dashboard()
+    import argparse
+    import time
+
+    parser = argparse.ArgumentParser(description="Dashboard interactive demo")
+    parser.add_argument("--initial-label", default="", metavar="LABEL",
+                        help="Ground truth label to pre-populate in the GUI")
+    parser.add_argument("--port", type=int, default=7778)
+    args = parser.parse_args()
+
+    def on_label(label):
+        print(f"[demo] ground_truth_label updated: {label!r}")
+
+    demo = Dashboard(
+        label_callback=on_label,
+        initial_label=args.initial_label,
+        port=args.port,
+    )
+    print(f"Dashboard running at http://localhost:{args.port}")
+    print("Type a label and press Enter to push it to the GUI, or Ctrl-C to quit.")
+    try:
+        while True:
+            label = input("label> ").strip()
+            if label:
+                demo.emit_label(label)
+                print(f"  → pushed {label!r} to browser")
+    except (KeyboardInterrupt, EOFError):
+        pass
+    finally:
+        demo.stop()

{dapps-0.0.7 → dapps-0.0.8}/src/visualization/templates/index.html

@@ -11,7 +11,11 @@
 <body>
     <div id="prbs"></div>
     <div id="magnitude"></div>
-    <div id="predicted_label"></div>
+    <div style="display: flex; align-items: center; justify-content: center; flex-wrap: wrap; gap: 24px;">
+        <div id="predicted_label"></div>
+        <div id="ground_truth_label"></div>
+        <div id="sampling_threshold_control"></div>
+    </div>
     <div id="adaptive_noise_floor"></div>
 
     <script>
@@ -32,7 +36,7 @@
 
         var waterfallLayout = {
             title: {
-                text: "Sensed Spectrum",
+                text: "dApp Sensed Spectrum",
                 font: { size: 16 }
             },
             xaxis: {
@@ -158,7 +162,7 @@
             }
         ],
             title: {
-                text: "PRB Status Grid",
+                text: "dApp PRB Status Grid",
                 font: { size: 16 }
             },
             xaxis: {
@@ -200,7 +204,7 @@
         var adaptiveNoiseFloorLayout = {
             title: {
                 text: "Adaptive Noise Floor",
-                font: {size: 24}
+                font: {size: 16}
             },
             xaxis: {
                 title: {
@@ -223,6 +227,15 @@
         var start_ignore;
         var end_ignore;
         var initialized = false;
+        var samplingThresholdInput;
+        var gtInput = null;
+        var gtBadge = null;
+        function updateBadge(label) { if (gtBadge) gtBadge.textContent = label; }
+        function flashBadge() {
+            if (!gtBadge) return;
+            gtBadge.style.outline = '3px solid #fbbc04';
+            setTimeout(function() { gtBadge.style.outline = 'none'; }, 400);
+        }
 
         var socket = io.connect('http://' + document.domain + ':' + location.port);
         socket.on('initialize_plot', function (data) {
@@ -260,6 +273,41 @@
             Plotly.newPlot('magnitude', waterfall, waterfallLayout);
             Plotly.newPlot('prbs', prbs, prbsLayout);
 
+            if (data.show_controls) {
+            var samplingThresholdContainer = document.getElementById('sampling_threshold_control');
+            samplingThresholdContainer.innerHTML = '';
+            samplingThresholdContainer.style.cssText = 'padding: 12px; font-family: sans-serif; display: flex; align-items: center; gap: 10px;';
+
+            var samplingThresholdLabel = document.createElement('label');
+            samplingThresholdLabel.textContent = 'Visualization sampling threshold:';
+            samplingThresholdLabel.style.cssText = 'font-size: 14px; font-weight: bold; white-space: nowrap;';
+            samplingThresholdContainer.appendChild(samplingThresholdLabel);
+
+            samplingThresholdInput = document.createElement('input');
+            samplingThresholdInput.type = 'number';
+            samplingThresholdInput.min = '1';
+            samplingThresholdInput.step = '1';
+            samplingThresholdInput.value = data.sampling_threshold;
+            samplingThresholdInput.style.cssText = 'font-size: 13px; padding: 5px 10px; border: 2px solid #ccc; border-radius: 4px; width: 100px; outline: none;';
+            samplingThresholdContainer.appendChild(samplingThresholdInput);
+
+            var samplingThresholdBtn = document.createElement('button');
+            samplingThresholdBtn.textContent = 'Set';
+            samplingThresholdBtn.style.cssText = 'padding: 5px 14px; font-size: 13px; background: #1a73e8; color: #fff; border: none; border-radius: 4px; cursor: pointer;';
+            samplingThresholdContainer.appendChild(samplingThresholdBtn);
+
+            function emitSamplingThreshold() {
+                var val = parseInt(samplingThresholdInput.value, 10);
+                if (!isNaN(val) && val >= 1) {
+                    socket.emit('set_sampling_threshold', val);
+                }
+            }
+            samplingThresholdBtn.addEventListener('click', emitSamplingThreshold);
+            samplingThresholdInput.addEventListener('keydown', function(e) {
+                if (e.key === 'Enter') emitSamplingThreshold();
+            });
+            } // end show_controls
+
             // PRB zone overlays — only drawn when control is active (PRB blocking enabled).
             // Without control there are no blocked PRBs so zone markers would be misleading.
             if (data.show_prb_zones) {
@@ -314,6 +362,54 @@
                 });
             }
 
+            if (data.show_label_selector) {
+                var container = document.getElementById('ground_truth_label');
+                container.innerHTML = '';
+                container.style.cssText = 'padding: 12px; font-family: sans-serif; display: flex; align-items: center; gap: 10px; flex-wrap: wrap;';
+
+                var heading = document.createElement('span');
+                heading.textContent = 'Ground Truth Label:';
+                heading.style.cssText = 'font-size: 14px; font-weight: bold; white-space: nowrap;';
+                container.appendChild(heading);
+
+                // Status badge
+                gtBadge = document.createElement('span');
+                gtBadge.style.cssText = 'font-size: 13px; font-weight: bold; padding: 4px 14px; border-radius: 12px; white-space: nowrap; transition: outline 0.1s; background: #5f6368; color: #fff;';
+                updateBadge(data.current_label);
+                container.appendChild(gtBadge);
+
+                // Free-text input for custom labels
+                gtInput = document.createElement('input');
+                gtInput.type = 'text';
+                gtInput.value = data.current_label;
+                gtInput.placeholder = 'custom label...';
+                gtInput.style.cssText = 'font-size: 13px; padding: 5px 10px; border: 2px solid #ccc; border-radius: 4px; width: 160px; outline: none;';
+                container.appendChild(gtInput);
+
+                var btn = document.createElement('button');
+                btn.textContent = 'Set';
+                btn.style.cssText = 'padding: 5px 14px; font-size: 13px; background: #1a73e8; color: #fff; border: none; border-radius: 4px; cursor: pointer;';
+                container.appendChild(btn);
+
+                var labelInitialized = false;
+                function emitLabel() {
+                    var val = gtInput.value.trim();
+                    if (val) {
+                        socket.emit('set_ground_truth_label', val);
+                        updateBadge(val);
+                        if (labelInitialized) flashBadge();
+                        labelInitialized = true;
+                    }
+                }
+
+                btn.addEventListener('click', emitLabel);
+                gtInput.addEventListener('keydown', function(e) {
+                    if (e.key === 'Enter') emitLabel();
+                });
+
+                emitLabel();
+            }
+
             // Dynamic preprocessing based on first_carrier_offset    
             // The carrier frequency is in the middle PRB (including DC leak on some radios)
             console.log("Initial values:", {
@@ -340,6 +436,26 @@
             initialized = true;
         });
 
+        socket.on('update_sampling_threshold', function (rate) {
+            samplingThresholdInput.value = rate;
+        });
+
+        socket.on('update_ground_truth_label', function (label) {
+            if (gtInput) gtInput.value = label;
+            updateBadge(label);
+            flashBadge();
+        });
+
+        socket.on('reset_waterfall', function () {
+            if (!initialized) return;
+            var rows = waterfall_buffer.length;
+            var cols = waterfall_buffer[0].length;
+            for (var i = 0; i < rows; i++) {
+                waterfall_buffer[i] = new Array(cols).fill(0);
+            }
+            Plotly.restyle('magnitude', { z: [waterfall_buffer] });
+        });
+
         socket.on('update_plot', function (data) {
             if (!initialized) {
                 return;

dapps-0.0.8/tests/test_dashboard.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""
+Tests for Dashboard — label callback, initial_label, and emit_label.
+"""
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
+
+from visualization.dashboard import Dashboard
+
+# port=0 lets the OS assign a free ephemeral port — avoids collisions between tests
+_PORT = 0
+
+
+def test_label_callback_fires():
+    received = []
+    d = Dashboard(label_callback=received.append, initial_label="no_rfi", port=_PORT)
+    assert d.label_callback is not None
+    assert d.current_label == "no_rfi"
+    d.label_callback("jammer")
+    assert received == ["jammer"]
+    d.stop()
+
+
+def test_emit_label_updates_current_label():
+    d = Dashboard(label_callback=lambda _: None, initial_label="no_rfi", port=_PORT)
+    d.emit_label("radar")
+    assert d.current_label == "radar"
+    d.stop()
+
+
+def test_no_label_callback_hides_selector():
+    d = Dashboard(port=_PORT)
+    assert d.label_callback is None
+    assert d.current_label == ""
+    d.stop()
+
+
+def test_initial_label_empty_by_default():
+    d = Dashboard(label_callback=lambda _: None, port=_PORT)
+    assert d.current_label == ""
+    d.stop()

{dapps-0.0.7 → dapps-0.0.8}/tests/test_iq_saver.py

@@ -10,10 +10,9 @@ from pathlib import Path
 import sys
 import os
 
-# Add parent directory to path for imports
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
 
-from spear.iq_saver.iq_saver import IQSaver
+from iq_saver.iq_saver import IQSaver
 import sigmf
 
 
@@ -394,6 +393,61 @@ def test_spectrum_dapp_integration_pattern():
         print("✓ Test 7 PASSED\n")
 
 
+def test_metadata_accumulation_across_flushes():
+    """Verify that repeated tofile calls accumulate all annotations, never losing earlier ones."""
+    print("=" * 80)
+    print("Test 8: Metadata accumulation across flushes")
+    print("=" * 80)
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        saver = IQSaver(
+            base_path=tmpdir,
+            center_freq=3.6192e9,
+            bandwidth=38.16e6,
+            annotation_flush_interval=200,  # manual flush only
+            num_prbs=106
+        )
+
+        samples = (np.random.randn(1024) + 1j * np.random.randn(1024)) * 1000
+        saver.save_samples(samples.astype(np.complex64))
+
+        # First batch of annotations, flushed to disk
+        saver.add_annotation(label='batch_1_a', comment='first flush, annotation A')
+        saver.add_annotation(label='batch_1_b', comment='first flush, annotation B')
+        saver.finalize_annotations()
+
+        meta_file = list(Path(tmpdir).glob('*.sigmf-meta'))[0]
+        with open(meta_file) as f:
+            meta = json.load(f)
+        assert len(meta.get('annotations', [])) == 2, "Expected 2 annotations after first flush"
+        print("✓ First flush: 2 annotations on disk")
+
+        # Second batch, flushed on top of the first
+        saver.add_annotation(label='batch_2_a', comment='second flush, annotation A')
+        saver.finalize_annotations()
+
+        with open(meta_file) as f:
+            meta = json.load(f)
+        assert len(meta.get('annotations', [])) == 3, \
+            f"Expected 3 annotations after second flush, got {len(meta.get('annotations', []))}"
+        print("✓ Second flush: all 3 annotations preserved on disk")
+
+        # Third batch flushed via close()
+        saver.add_annotation(label='batch_3_a', comment='third flush via close')
+        saver.close()
+
+        with open(meta_file) as f:
+            meta = json.load(f)
+        assert len(meta.get('annotations', [])) == 4, \
+            f"Expected 4 annotations after close, got {len(meta.get('annotations', []))}"
+        labels = [a.get('core:label') for a in meta['annotations']]
+        assert 'batch_1_a' in labels and 'batch_1_b' in labels
+        assert 'batch_2_a' in labels
+        assert 'batch_3_a' in labels
+        print("✓ close(): all 4 annotations preserved, no data lost across flushes")
+        print("✓ Test 8 PASSED\n")
+
+
 if __name__ == "__main__":
     print("\n" + "=" * 80)
     print("IQSaver Test Suite")
@@ -407,6 +461,7 @@ if __name__ == "__main__":
         test_context_manager,
         test_deferred_annotations,
         test_spectrum_dapp_integration_pattern,
+        test_metadata_accumulation_across_flushes,
     ]
     
     passed = 0

dapps-0.0.7/VERSION

@@ -1 +0,0 @@
-0.0.7